//////////////////////////////////////////////////////////////////////////////
// Copyright (c) 2010, 2026 Contributors to the Eclipse Foundation
//
// See the NOTICE file(s) distributed with this work for additional
// information regarding copyright ownership.
//
// This program and the accompanying materials are made available
// under the terms of the MIT License which is available at
// https://opensource.org/licenses/MIT
//
// SPDX-License-Identifier: MIT
//////////////////////////////////////////////////////////////////////////////

include::_part_attributes.asciidoc[]

indexterm:[build]
indexterm:[Maven]
indexterm:[Tycho]
indexterm:[Jenkins]
indexterm:[test]
indexterm:[JUnit]

:leveloffset: -2

[[development-building-and-testing-chapter-index]]
== Building and testing

This page explains:

* <<development-building-and-testing-chapter-index-building,Building Eclipse ESCET>>
* <<development-building-and-testing-chapter-index-testing,Testing Eclipse ESCET>>

[[development-building-and-testing-chapter-index-building]]
=== 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 link:https://eclipse.dev/escet/{escet-deploy-folder-name}/download.html[download] and use an ESCET release, be it a final release or a nightly version.
* If you set up an Eclipse-based <<development-dev-env-setup-chapter-index,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 menu:Window[Perspective > Open Perspective > Other...], selecting the _Java (default)_ perspective and clicking btn:[OK].
** Select menu: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 btn:[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 btn:[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):

[[development-building-and-testing-force-build]]
* 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-development-process-chapter-index,development process>> and <<development-contributing-contribute,contributing information>>.
** Go to the Eclipse ESCET Jenkins server at link: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 menu: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-dev-env-setup-chapter-index,development environment>>:
** Activate the Java perspective, using menu:Window[Perspective > Open Perspective > Other...], selecting the _Java (default)_ perspective and clicking btn:[OK].
** Select menu: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 btn:[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 kbd:[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 kbd:[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 https://en.wikipedia.org/wiki/X_Window_System[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`.

[[development-building-and-testing-chapter-index-testing]]
=== 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 <<development-building-and-testing-chapter-index-building,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.

. Run the integration test under the _JUnit Plug-in Test_ section of the _Run Configurations_ dialog (e.g. _test-cif-integration_).
. If an output differs from the expected output, the output is saved with a `.real` postfix.
. 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_).
. Run the integration test again to ensure that all expected test outputs have been updated.
. Before committing the changes, check whether the differences are as expected.
