Eclipse Plug-ins

BASIS offers BDT and Enterprise Manager plug-ins for the Eclipse IDE, as well as the experimental BBjUtilities plug-in of additional utilities.  This page describes how to set up a development computer for those plug-ins so that you can develop BBj code for the current versions of BBj, versions 22.xx, with the latest Java 11 or Java 17 LTS (“Long Term Support” release) and the correct version of Eclipse for Java Developers.

NOTE: Java 17 requires you to add several Java virtual machine arguments to get BDT's WindowBuilder to open ARC files. To use Java 17 with Eclipse 2022-03, be sure to follow bullet #5 of Step 3 below and add the vmargs listed to your eclipse.ini file.

NOTE: Eclipse 2022-12 includes a change that breaks compatibility with BDT versions 22.xx and earlier. If you attempt to use Eclipse 2022-12 with an existing BDT, you will find that some user actions fail silently (the most obvious is creating a new BBj Project). The cause of the underlying problem is a re-packaging of the databinding classes (see Eclipse's Bug 546822). You can confirm that this is the problem by locating an "unhandled event loop exception" error in Eclipse's .log file; it also appears in the Eclipse Error Log view. BASIS anticipates that this issue will be resolved with the release of BDT 23.00, which will be compatible with Eclipse 2023-03 and beyond.

Installation Instructions

For information about setting up earlier versions of Eclipse and Java, see the Eclipse Setup - Historical Plug-Ins page. 

Follow the steps below in the order they are presented to set up a development computer for BBj 22.xx.

STEP 1: JAVA

Before you install BBj, Eclipse, or the BASIS Plug-ins on a development computer, you must download and install the latest Java Development Kit (the JDK, not the JRE) for Java 11 or Java 17 (the “Long Term Support” release). BBj 22.xx is tested to run with either LTS version.

For an overview of the issues and options related to selecting the correct version, see BASIS’ Java Break titled “The End of Free Oracle Java! What to do?”. Although this presentation was created during the early days of the transition period where OpenJDK versions were not yet available, the other information it contains may be helpful to you as you make your decision.

STEP 2: BBj

Now that you have installed Java 11 or 17, proceed to download and install the latest BBj 22.xx. Go to BASIS’ product download page (https://www.basis.cloud/download-product), select the product, version, package, and build (timestamp). Download the installation jar file and run it to complete the BBj installation.  In any case, remember where you installed BBj as you will need to tell the BDT plug-ins where this “BBj Installation” is in order to run.

STEP 3: ECLIPSE

Now that you have installed Java and BBj 22.xx, proceed to download and install Eclipse version 4.23 (Eclipse 2022-03):

NOTE: newer 2022-xx versions may also be valid, but BASIS has not verified those versions with BBj 22.xx.

NOTE: You may have multiple Eclipse installations on one development computer as long as they are installed in separate folders.

1. Go to the following website to obtain the Eclipse 2022-03 IDE for Java Developers:
   https://www.eclipse.org/downloads/packages/release/2022-03/r
2. Scroll as necessary to reach the section titled Eclipse IDE for Java Developers.
3. On the right side of that section, select your operating system and architecture: Windows x86_64, macOS x86_64, Linux x86_64, or AArch64. Follow the instructions to select a mirror site and download a .zip file (Windows) or .tar.gz file (Mac or Linux) to your computer.
4. Once the download is complete, extract the entire contents of the compressed file to a location of your choosing on your computer; this “installs” Eclipse 2022-03 on your computer.
5.  Locate the eclipse.ini file in the Eclipse 2022-03 installation folder, and edit it with any ASCII text editor to add the following lines:

   --add-exports=java.desktop/sun.awt.shell=ALL-UNNAMED
   --add-opens=java.base/java.lang=ALL-UNNAMED
   --add-exports=java.desktop/sun.swing=ALL-UNNAMED
   immediately following the “-vmargs” line exactly as shown in the screenshot below:

• Eclipse IDE Tutorial #1
• Eclipse IDE Tutorial #2
• Resources
• Shortcuts

STEP 4: BASIS PLUG-INS

Now that you have installed Java, BBj 22.xx, and Eclipse 2022-03, install the BASIS plug-ins in Eclipse.  To do so, follow these instructions using the URL of your choice from the table below the procedure steps:

1. Launch Eclipse (run the eclipse or eclipse.exe executable, in your Eclipse installation folder).
2. In Eclipse’s main menu, select Help > Install New Software...
3. Click [Add...] to open Eclipse’s Add Repository window.
4. In this document, examine the table below these instructions and decide whether you wish to install the “LATEST OFFICIAL 22.xx RELEASE” plug-in or the “LATEST 22.xx RELEASE CANDIDATE” plug-in. The differences?
   • The plug-in versions downloadable from the URL in the “OFFICIAL” column are always the recent versions of BBj that BASIS has tested and officially released.
   •  The plug-in versions downloadable from the URL in the “RELEASE CANDIDATE” column are more recent versions that likely contain bug fixes and new features that are under development. These “RELEASE CANDIDATE” BBj 22.xx versions are not fully tested, but are in the process of being evaluated and tested as part of an upcoming official release.
     
     For more guidance on selecting the correct version for you, see the explanatory information below the table.
5. Right-click the URL in the column you have chosen, and select “Copy link address” (or the closest equivalent, the exact text can vary by browser). This copies the URL to your cut-and-paste buffer.
6. Returning to Eclipse, paste the URL in the “Location:” field of Eclipse’s Add Repository window (be sure to delete any text that was already there first).
7. In the "Name:" field of Eclipse’s Add Repository window, enter a short unique name for Eclipse to display whenever it needs to refer to this URL.
8. Click [Add]. Once Eclipse contacts the URL and updates its Install window, you should have entries for: BBj Utilities, BDT, BLTK, and Enterprise Manager.
9. Check the box next to each entry in the list field that you want to install. There are dependencies between some of the entries - see the list below for details. When in doubt, check them all.
   • BBj Utilities (the optional experimental utilities for BBj development, you must also install BDT and BLTK)
   • BDT (you must also install BLTK)
   • BLTK (a library used by BDT)
   • Enterprise Manager (independent of the other BASIS plug-ins)
10. Ensure that the “Contact all update sites during install to find required software” box is checked.
11. Check the other boxes as you wish.
12. Follow the remaining instructions (including accepting the license agreements) as appropriate based on the plug-ins selected in order to complete the installation.
13. Once the Install window completes successfully, you may be prompted to restart Eclipse. If so, the new plug-ins will not be available to use until after you have restarted, so you should restart Eclipse.

BASIS Plug-in Details

A number of BASIS plug-ins are available for Eclipse. The following tables list the URLs of the composite Eclipse P2 repositories from which one or more of those plug-ins can be installed. To install a plug-in, follow the instructions outlined above using a URL from the table below:

*You must also install the BASIS Language ToolKit (BLTK) because it is a prerequisite for the BDT plug-ins.

**You must also install the BLTK and BDT plug-ins, because they are prerequisites for the BBjUtils plug-ins.

***The PRO/5 Compiler plug-in was added to BBj Utilities with the BBj 17.00 release.

For information about accessing earlier versions of the plug-ins, see the Historical Plug-In URLs page.

BASIS Plug-In Notes

• All of the plug-ins listed with the same URL can be installed at one time.
• The BASIS plug-in URLs listed are exact, so do not replace the "xx" characters in the URLs with specific digits.
• There is only one Composite 22xx URL (https://plugins.basis.cloud/composite/22xx) and it offers all of the "latest official 22.xx release" plug-ins.
• The https://plugins.basis.cloud/composite/22xxrc URL offers updated plug-ins that are being tested in preparation for the next 22.xx release.
• For a very short period immediately following an official release, both the https://plugins.basis.cloud/composite/22xx and the https://plugins.basis.cloud/composite/22xxrc URLs will offer the same downloads (the final release candidate will have become the officially released version). These two will only remain identical until a new release candidate becomes available, starting the cycle over again. This could happen as early as the next daily build.

Each BASIS plug-in URL correlates to a major version number for BDT, as noted in its name. BASIS recommends the following:

• You should always update the plug-ins and BBj together (at the same time).
• You should always match the major version numbers for BBj and BDT. For example, you should only install a BBj 22.xx on your development computer to accompany any BDT 22.xx plug-ins.
• You should update BBj to the most recent 22.xx version (official or release candidate) when you update the BDT plug-ins to the most recent version (official or release candidate). BDT relies heavily on BBj for its functionality, and many fixes for BDT actually depend on BBj to provide that functionality.

(Return to Top)

OPTIONAL THIRD PARTY PLUG-INS

Optionally, you may choose to install a third-party plug-in from inside Eclipse using the Marketplace Keyword (if one is available in the table below), or click the hyperlink in the PLUG-IN column and follow the instructions on the website. To install using the Marketplace Keyword, follow these steps:

1. Copy the text shown in the Marketplace Keyword column.
2. Launch Eclipse and select the menu item Help > Eclipse Marketplace.....
3. Paste the keyword into the ‘Find:’ field.
4. Click [Go] to search..
5. Select the desired plug-in from the results and click [Install].
6. Follow the remaining instructions to complete the installation.

TOOLS ACCESSIBLE VIA BASIS PLUG-INS

(Return to Top)