Skip to content

Configure a development environment

Jump to bottom
Paul Elder edited this page May 15, 2023 · 1 revision

Overview

These instructions lead you through configuration of a CX4CBDDS development environment. This is a 'quick-and-dirty' method. It omits some tools needed to modify specific source artifacts (missing: Xtend2 template editing, UML2 model editing, 'DDK' code generation). However, it allows you to import the GitHub project, and quickly run and debug a Papyrus CX instance

Prerequisites

Ensure that curl and git are installed. On Linux, these are available via your package manager.

Install a Java 11 JDK

CX4CBDDS (Papyrus CX) is currently built with Java 11, which you must install on your machine. There are a number of ways to do this. Choose the one that resonates with you.

SDKMan

If you like an easy and reliable way to switch between JDKs, consider using SDKMan. Note that is works best on Unix-like platforms. Once installed, the following SDKman commands are useful:

List available installs (filtering for those available from Eclipse Temurin):

sdk list java | grep tem

Install an Eclipse Temurin JDK 11 from the above list:

sdk install java 11.0.19-tem

Find the JAVA Home for an installed JDK:

sdk home java 11.0.19-tem

Download an Eclipse Temurin JDK

Alternately, Eclipse Temurin has OpenJDK 11 builds available.

Use a host-OS package manager

Lastly, Linux package managers many also be used.

Install the Eclipse installer

  1. Navigate to the Eclipse downloads page
  2. On the left-hand side of the page, choose the download button for your architecture. (As of 2023-03, the download includes the required JRE.)
  3. Extract the downloaded archive file (the extension and tools will vary, depending on you operating system).
  4. Navigate into the extracted folder to find eclipse-inst. Double-click it to start the installer.

Install "Eclipse IDE for Eclipse Committers"

  1. With the Eclipse installer running, select Eclipse IDE for Eclipse Committers and click Next.
  2. Click Next to move through the Projects wizard page without change.
  3. Provide a name for your installation folder. (It will be created in your home directory.)
  4. Click Next, then on the Confirmation page, click Finish.
  5. During the installation, you may be prompted to accept licenses, to accept code signing certificates or to accept unsigned code. In each case, accept and continue.
  6. After the installation completes, click Finish once again. Your new IDE will start.

Prepare a development workspace

Complete the following in your new IDE:

  1. Create a workspace name. One is proposed, but you can choose whatever name you like, in any folder you like.
  2. If presented with a Welcome screen, close it.
  3. Configure the JDK 11 you installed above:
    1. Choose Windows > Preferences. Type jre to filter the available choices, and choose Installed JREs.
    2. Click Add, and accept Standard VM as the JRE type and click Next.
    3. Enter the 'home' directory of the JDK 11 you installed earlier. Click Finish.
    4. Check the newly installed JRE in the Installed JREs page and click Apply and Close.
  4. Configure GIT to checkout:
    1. Open the GIT perspective (Window > Perspective > Open Perspective > Other).
    2. If you have not already cloned CX4CBDDS, choose Clone a Git repository and follow the instructions in the wizard. DO NOT import existing projects at this time.
    3. If CX4CBDDS is already closed, choose Add an existing local Git repository.
  5. Ensure that the papyrus branch is checked out. If not:
    1. Expand CX4CBDDS > Branches > Remote Tracking, find origin/papyrus, right click, and choose Checkout.
  6. Import existing projects into the Eclipse workspace:
    1. Right click CX4CBDDS > Working Tree, and choose Import Projects.
    2. Click Finish, to run the import wizard without changes.
  7. Organize you workspace for development:
    1. Open the Plug-in Development perspective (Window > Perspective > Open Perspective > Other).
    2. In the Project view, expand dds4ccm to reveal tests. Expand tests and select all the projects underneath it. Right click and choose Close Projects.
  8. Disable API baselines:
    1. Click Window > Preferences and type baseline to filter. Choose API Baselines. From the Missing API baseline drop down, choose Ignore, then click Apply and Close. If prompted, click Build.
  9. Setup a 'Target Platform', which will eliminate compile errors:
    1. Close Window > Preferences, type target to filter, and choose Target Platform.
    2. Check the Papyrus CX for AXCIOMA... whose path starts with /dds4ccm/. (You may have to make the dialog wider to see this.)
    3. Click Apply and Close.
    4. Watch the 'progress' indicator (lower-right) as it resolves the platform and rebuilds the workspace. Once complete, the Problems view should show no errors (although it will still show warnings.)
  10. Create a 'launch configuration' to run Papyrus CX from within your development IDE:
    1. From the menu, click Run > Run Configurations.
    2. Click Eclipse Application, then click the icon showing a page with a small yellow plus-sign in the top-right corner (hover text is New launch configuration.
    3. For Name, enter papyrus-cx (or some other name meaningful to you).
    4. From the Run a product drop-down, choose com.zeligsoft.papyrus-cx.axcioma.rcp.product.
    5. Click Run to start Papyrus-CX.
    6. After you have explored a bit, exit (From the menu, choose File > Exit.)

Using your launch configuration

Your launch configuration is saved in your development IDE.

  1. You can easily re-launch it from either the Run menu (Run > Run History) or from the Run toolbar icon (green circle with a white triangle within).
  2. The launch configuration is also used to start the Eclipse debugger. (The green bug icon immediately to the left of the run icon.) A debug instance of Papyrus CX looks identical to a 'run' version; the only difference is that you can use the debugger against it.

Using the debugger

The 'Debug Perspective' is useful. (Menu Window > Perspective > Open Perspective > Other, then Debug.

You can use the Project Explorer view to find source code (and then set breakpoints).

You can use the Console view to see console output from the running Papyrus CX. Stack traces can be printed here, which can serve as links back to the code.

From the Debug view, you can select a thread (for example main, the UI thread), and then suspend it using the suspend icon (two vertical yellow bars) on the toolbar. The resume icon can resume a thread.

From the Breakpoints view, you can see, edit and remove breakpoints. Breakpoints are generally added by double-clicking in the left-margin of a source file.

The process for finding a bug.

If you have a stack trace, finding the source file/line and setting a break point there is a great start. When you hit a breakpoint, you can look at variable values (Variables views), amongst many other things.

Sometimes, you get lucky, and that's all you need. Most times, however, you need to do more, including setting breakpoints earlier in the flow, to see what's happening.

One particularly frustrating aspect of debugging is having to stop at the same line over and over again. Conditional breakpoints can make this less tedious: you can write a Java expression that must evaluate to true before the debugger will actually stop. Be forewarned that evaluating conditional breakpoints can noticeably slow down execution.

Another use for conditional breakpoints is to introduce 'trace' statements. You can put any group of statements you want in a conditional breakpoint, including print statements! So a 'trace' break point might call System.out.println (printing variable values) and then return false (to not stop). The println output will still show in the Console view.

You can also set breakpoints when certain exceptions are thrown.

Clone this wiki locally