Building and testing

This page explains:

Building

In most cases, it is not needed to build the Eclipse ESCET software yourself:

  • If you want to just use the ESCET toolkit, you can simply download and use an ESCET release, be it a final release or a nightly version.

  • If you set up an Eclipse-based development environment for Eclipse ESCET, then all code is automatically compiled on the background at the first launch, and recompiled whenever you change the code. You can then launch a so-called ESCET 'runtime instance' from your ESCET development environment. A 'runtime instance' works much like an ESCET IDE release, but it runs the code that you have in your development environment. You can run it as follows:

    • Activate the Java perspective, using Window  Perspective  Open Perspective  Other…, selecting the Java (default) perspective and clicking OK.

    • Select Run  Run Configurations… to open the Run Configurations dialog. From the list at the left, under Eclipse Application, select the escet-product launch configuration, and click the Run button to start the 'runtime instance'.

    • If instead of the Run Configurations dialog you open the Debug Configuration dialog, select the escet-product launch configuration, and click the Debug button, you’ll start a 'runtime instance' with your development environment attached as debugger. This means you can add breakpoints in your development environment, hot-swap changed code to the 'runtime instance' without restarting it (in most cases), and so on.

If you do want to build Eclipse ESCET yourself, it is good to know that the ESCET build is based on Maven/Tycho. The build will build every individual plugin and feature, as well as the update site, IDE (called 'product' in Eclipse terminology) and all documentation.

The following options are available to build the ESCET software (in order from most recommended to least recommended):

  • The build server automatically builds every branch and merge request of the official ESCET repo:

    • Every branch of the official ESCET repo is automatically built, but not branches of forks. All merge request submitted to the official ESCET repo are automatically built, but not merge requests submitted to forks. For more information, see our development process and contributing information.

    • Go to the Eclipse ESCET Jenkins server at https://ci.eclipse.org/escet/, select the desired build and then the branch or merge request of interest, to see the build results.

    • If for some reason the build server doesn’t automatically pick up a branch or merge request, login to Jenkins, open the desired build and select Scan GitLab Project Now to force GitLab to scan for new branches, commits, etc. Only ESCET project leads and committers can force a scan.

  • Run the build in an ESCET development environment:

    • Activate the Java perspective, using Window  Perspective  Open Perspective  Other…, selecting the Java (default) perspective and clicking OK.

    • Select Run  Run Configurations… to open the Run Configurations dialog. From the list at the left, under Maven Build, select the build launch configuration, and click the Run button to run the build.

    • Additional launch configurations are available to build documentation projects separately.

  • On Windows, in a command prompt, with the root of the Git repository as current directory, enter .\build.cmd and press Enter. This requires Java and Maven to be available on your system (to be on your PATH). The script checks the minimum-required Java and Maven version constraints.

  • On Linux/macOS, in a shell, with the root of the Git repository as current directory, enter ./build.sh and press Enter. This requires Java and Maven to be available on your system (to be on your PATH). The script checks the minimum-required Java and Maven version constraints.

    The build requires a working X Window System. If one is not available, for instance on headless systems, you could try running xvfb-run --auto-servernum ./build.sh instead of ./build.sh.

Testing

Eclipse ESCET has various tests, ranging from unit tests to integration tests. The tests can be executed in various ways:

  • As part of the build, all tests are performed as well.

  • A single test-all launch configuration to run all tests is available under the Launch Group section of the Run Configurations dialog.

  • Launch configurations to run various subsets of the tests are also available, under the JUnit Test and JUnit Plug-in Test sections of the Run Configurations dialog.

When a tool has been updated, the test outputs may change. The expected outputs can be updated as follows.

  1. Run the integration test under the JUnit Plug-in Test section of the Run Configurations dialog (e.g. test-cif-integration).

  2. If an output differs from the expected output, the output is saved with a .real postfix.

  3. Run the copy all script under JUnit Plug-in Test section to replace the expected outputs with the test outputs (e.g. test-cif-integration-copy-all).

  4. Run the integration test again to ensure that all expected test outputs have been updated.

  5. Before committing the changes, check whether the differences are as expected.