===== Develop GroIMP in Eclipse =====

This guide is written to give new GroIMP developers an overview about how the required development environment is prepared and installed.

This guide starts with the installation of Eclipse and ends with a merge request for the own code changes.

The plan is to do following steps:

  - Installing **Eclipse**. This can be skipped if it is already installed.
  - **Cloning** the fork repository to the local computer (in Eclipse)
  - Adjusting the **compiler** and **Java version**
  - Setting up a **start** configuration
  - **Pushing** code to the own remote repository (fork of official repository)
  - Creating a **merge request** for the own code changes

==== General information ====

  * This guide is based on the usage of Linux. Except the installation of Eclipse, all steps should also be reproducable on Windows or other systems.
  * GroIMP is best compatible with Java 11 for both compilation and execution. It is possible to run GroIMP in newer version of Java, but for Java version 17+, the OpenGL view is not supported.


==== Requirements ====

  * Experience with Java and Git
  * A gitlab account on [[ https://gitlab.com | Gitlab]] for cloning in Eclipse (**optional** if the cloning is done without Eclipse).
  * Java >= 17


==== Installing Eclipse ====

=== Windows ===

On Windows, an Eclipse installer can be downloaded from the [[ https://www.eclipse.org/downloads/packages/release/kepler/sr1/eclipse-ide-java-developershttps://www.eclipse.org/downloads/packages/release/kepler/sr1/eclipse-ide-java-developers | official website]]. Then, you can execute the installer.

=== Linux ===

If an older Eclipse is installed and should be removed, execute one of the following commands:

If it was installed with `apt`:

<code>
sudo apt-get autoremove --purge eclipse
</code>

If it was installed with `snap`:

<code>
sudo snap remove eclipse
</code>

Now, update the system and make sure that Java is installed:
<code>
sudo apt-get update
sudo apt-get install default-jre
</code>

Then, install Eclipse. This is the way with `apt`:
<code>
sudo apt-get install eclipse
</code>

Otherwise, it can be installed with `snap`. This is also the right way if the used Linux is an older one (for example Ubuntu 18.04). The current version of Eclipse is not compatible with older Linux distributions:

<code>
sudo snap install --classic eclipse
</code>


==== Cloning the repository ====

It is possible (and recommended) to clone the git repository without Eclipse. More information [[:dev-guide:getting-started|there]].

=== From Eclipse egit ===

**Warning: This method sometime lead to error in the code compilation. It is not recommended to use it.** 

The git repository can be imported in Eclipse using the eclipse plugin eGit, which is embedded by default in all Eclipse installations.

Click on File > Import…

Open the category `Git`

Select Projects from Git

Select `Clone URI`

Insert `git@gitlab.com:yourgitlabprefix/groimp.git` into the URI field and replace the prefix with your prefix where to find the forked repository.


==== Import the repository in Eclipse ====

You have the repository with GroIMP source code on your local device. 

In Eclipse, click on //File > Import...//

Open the category `Maven`.

Select `Existing Maven Projects`.

Set the Root Directory as the groimp repository you downloaded.

All GroIMP plugins should appear in the projects list. 

Click on `Finish`.

==== Setting up Java Runtime Environment ====

To setup the JRE, go to //Java > Installed JREs//.

In Eclipse, the default JRE used can be an embedded JRE from Eclipse, which will not work with GroIMP. 
If it is the case, add a new JRE by clicking on `Add...`, `Standard VM`, then, point at the root of a JDK on your computer (e.g. /usr/lib/jvm/jdk11 for linux or C:\Program Files\java\jdk11 on Windows). 

Make sure that this version is selected.

Notice that a newer version of Java can work but might not be compatible with the OpenGL 3D view.

In case of changes, click //Apply//.

==== Setting up the compiler ====

The next step is to set the compliance level. Therefore, go to //Java > Compiler//.

Set the `Compiler compliance level` to `17`. The warning on the bottom can be ignored.

Then click on //Apply and Close//.

Eclipse will ask whether all projects should be rebuilt now, click on //Yes//.

Depending on your computer, the build process may take some minutes.

==== Setting up Start configuration ====

=== Maven resouces copy ===

GroIMP uses some third party library, which are not automatically downloaded with the source code. To run GroIMP in Eclipse you need to force their download into your local repository.

This operation is only required every time you clean the project with Maven. Eclipse will not delete the libraries.

Either use `mvn generate-resources` in a terminal at the root of the project, or in Eclipse 
go to //Run > Run Configurations...//.

In the menu on the left, select `Maven Build`. In the menu on the right select the root directory as `Base directory`, either by clicking `Workspace...`>`GroIMP`, or by setting `${workspace_loc:/GroIMP}`.

Then, set the `Goals` as `generate-resources`.

Click on `Apply`, then `Run`.

This should copy all third parties libraries defined in the poms files of your projects to their target/lib repository, making it visible to GroIMP.

=== Start the platfrom ===

Now you need to set up the main GroIMP class to be run.

Go to //Run > Run Configurations...//.

In the menu on the left side in the following window, select `Java Application` and click the most left button in the symbol menu above to create a new java application starter.

Give the starter a good name, for example `GroIMP`.

Select the project `Platform-Core` if it is not selected automatically.

Select the main class `de.grogra.pf.boot.Main` if it is not selected automatically. Make sure to select it from the //Search...// button, if you write down the class name yourself Eclipse might not make the connection.

Then, click on //Apply// and go to the tab `x() = Arguments`.

For the program arguments, a very special parameter `--project-tree` is required. This parameter is important because the directory structure differs between the development version in Eclipse and the ready-to-use installed version. GroIMP needs this parameter to search in differing directories for plugins and configuration files. If this parameter is missing in the Eclipse development version, GroIMP will show an error window with the text "No application found".

For the JVM arguments, add `-Xmx3000m`. If required, more or less memory can be specified here instead of 3000 MB.

Check [[:User-Guide:Advanced-GroIMP-arguments | GroIMP additional arguments]] for more information on the most common arguments you can change when running GroIMP.