//////////////////////////////////////////////////////////////////////////////
// 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[]

:leveloffset: -2

[[development-dev-env-setup-chapter-index]]
== Development environment setup

Follow these instructions to set up an Eclipse ESCET development environment.

indexterm:[installer]
indexterm:[oomph]
indexterm:[oomph, setup]
indexterm:[development, environment]

To create a development environment for the first time:

* Get the Eclipse Installer:
** Go to link:https://www.eclipse.org/[] in a browser.
** Click on the big btn:[Download] button at the top right.
** Download the Eclipse Installer by clicking below the _Install your favorite desktop IDE packages_ text on the btn:[Download] button and selecting the appropriate download option for your CPU architecture.
* Start the Eclipse Installer that you downloaded.
* Use the hamburger menu at the top right to switch to advanced mode.
* For Windows:
** When asked to keep the installer in a permanent location, choose to do so.
Select a directory of your choosing.
** The Eclipse installer will start automatically in advanced mode, from the new permanent location.
* For Linux:
** The Eclipse installer will restart in advanced mode.
* Continue with non-first time instructions for setting up a development environment.

To create a development environment for a non-first time:

* Ensure you are using the latest version of the Eclipse Installer:
** One option is to download it again, as per the 'first time' instructions above.
** Another option is to update your existing Eclipse Installer.
In the Eclipse Installer, when in advanced mode, click the 'Install available updates' button.
This button with the two-arrows icon is located at the bottom-left part of the window, next to the version number.
Wait for the update to complete and the Eclipse Installer to restart.
If the button is disabled (grey), you are already using the latest version.
* In the first wizard window:
** Select _Eclipse Platform_ from the big list at the top.
** Select _2025-09_ for _Product Version_.
** For _Java 21+ VM_ select _JRE 21.x.x - \https://download.eclipse.org/justj/jres/21/updates/release/latest_.
** Choose whether you want a P2 bundle pool (recommended).
** Click btn:[Next].
* In the second wizard window:
** Use the green '+' icon at the top right to add the Oomph setup.
*** For _Catalog_, choose _Eclipse Projects_.
*** For _Resource URIs_, enter `+https://gitlab.eclipse.org/eclipse/escet/escet/-/raw/develop/org.eclipse.escet.setup+` and make sure there are no spaces before or after the URL.
*** Click btn:[OK].
** Check the checkbox for _Eclipse ESCET_, from the big list.
It is under _Eclipse Projects_ / _<User>_.
** At the bottom right, select the _develop_ stream.
** Click btn:[Next].
* In the third wizard window:
** Enable the _Show all variables_ option to show all options.
** Choose a _Root install folder_ and _Installation folder name_.
The new development environment will be put at `<root_installation_folder>/<installation_folder_name>`.
** Fill in the _Eclipse ESCET Git clone URL_:
*** Committers with write access to the Eclipse ESCET official GitLab repository can use the default URL `+https://gitlab.eclipse.org/eclipse/escet/escet.git+`.
*** Contributors can use the same URL, but as they don't have write access, they will not be able to push to the remote repository.
They can instead make a fork of the official Git repository, as described in the <<development-contributing-chapter-index,contributing>> section.
Then they can fill in the URL of their clone instead, i.e. `+https://gitlab.eclipse.org/<username>/<cloned_repo_name>.git+`, with `<username>` replaced by their Eclipse Foundation account username, and `<cloned_repo_name>` replaced by the name of the cloned repistory, which defaults to `escet`.
** For _Eclipse Foundation account full name_ fill in your full name (first and last name) matching the full name in your Eclipse Foundation account.
This will be used as name for Git commits.
** For _Eclipse Foundation account email address_ fill in the email address associated with your Eclipse Foundation account.
This will be used as email for Git commits.
** Click btn:[Next].
* In the fourth wizard window:
** Select btn:[Finish].
* Wait for the setup to complete and the new development environment to be launched.
** If asked, accept any licenses and certificates.
** If you get a _Trust_ dialog, click btn:[Select All] and then btn:[Trust Selected].
* Press btn:[Finish] in the Eclipse Installer to close the Eclipse Installer.
* If you're running Windows as your operating system and you have Windows Defender as your virus scanner, the new development environment may show a dialog about Windows Defender decreasing the performance of the Eclipse IDE.
Choose to exclude the development environment from being scanned by Windows Defender if possible, provided you accept the associated risks, to ensure a smooth development experience.
* Observe Oomph executing the startup tasks (such as Git clone, importing projects, etc).
If this is not automatically shown, click the rotating arrows icon in the status bar (bottom right) of the new development environment.
* Wait for the startup tasks to finish successfully.
* NOTE: If you don't open the Oomph dialog, the status bar icon may disappear when the tasks are successfully completed.

If you have any issues during setting up the development environment, consider the following:

* You can set the following environment variables to force the use of IPv4, in case of any issues accessing/downloading remote files:
+
[source]
----
_JAVA_OPTIONS=-Djava.net.preferIPv4Stack=true
_JPI_VM_OPTIONS=-Djava.net.preferIPv4Stack=true
----
+
After setting them, make sure to fully close the Eclipse Installer and then start it again, for the changes to be picked up.

In your new development environment, consider changing the following settings:

* Activate the Java perspective, using menu:Window[Perspective > Open Perspective > Other...], selecting the _Java (default)_ perspective and clicking btn:[OK].
* For the _Package Explorer_ view:
** Enable the _Link with Editor_ setting, using the image:{development-imgsdir}/link-with-editor.png[] icon.
** Enable showing resources (files/folders) with names starting with a period.
Open the _View Menu_ (image:{development-imgsdir}/view-menu.png[]) and choose menu:Filters...[].
Uncheck the `+.* resources+` option and click btn:[OK].
