GroIMP wiki

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== Setup GroIMP with Git and Eclipse ======

In this tutorial we will cover how to:
  * Use Git to download GroIMP source code
  * Use Maven to compile the code 
  * Set up Eclipse as IDE

You can find more in depth info on :
  * [[05_developer_tutorials:01_setup:getting-started|Download the source code]]
  * [[05_developer_tutorials:01_setup:developer-guide|Set up Eclipse]]
  * [[https://docs.gitlab.com/ee/user/packages/maven_repository/|Set up a Maven token]]
  * [[05_developer_tutorials:dev-guide:maven-commands|Additional commands with maven]]

===== Installation of required tools =====

In this tutorial we will use the following software (make sure they are installed on your computer):
  * **Git**: On Linux system this is usually installed by default. On windows or MAC you can follow the tutorial from [[https://github.com/git-guides/install-git|Github]].
  * **Maven**: On Debian system you can get Maven with ''sudo apt install maven -y''. On Windows, you can download the archive [[https://maven.apache.org/download.cgi|on the official website]], unzip the file, and add it to the PATH variable.
  * **Eclipse**: For Debian systems you can follow the tutorial on the [[https://wiki.debian.org/Eclipse|debian website]]: On Windows, you can download the installer from the [[https://www.eclipse.org/downloads/download.php?file=/oomph/epp/2024-09/R/eclipse-inst-jre-win64.exe|eclipse website]].
  * [[https://www.perl.org/get.html|Perl]]
===== Download GroIMP source code =====

GroIMP source code is hosted on [[https://gitlab.com/grogra/|gitlab]]. It is split between the [[https://gitlab.com/grogra/groimp|core]] - which includes the core plugin to start GroIMP (but not RGG modeling); and the [[https://gitlab.com/grogra/groimp-plugins|additional plugins]].

It is possible to download each gitlab repositories without creating accounts from the web page:

{{:tutorials:gitlab_dl.png?200|}}

In order to properly push back modifications, it is recommended to get the sources using git. In order to do so, you need to have a GitLab account (which you can create [[https://gitlab.com/users/sign_up|here]]).

Once you are registered, you can fork the project: (see the two following images)
  * Go to the git repository page in your internet browser.
  * Click on the //Fork// button of the repository. (img 1)
  * Select your own gitlab namespace and optionally an other project name (not recommended). (img 2.1)
  * Only get the main branch (it is smaller) (img 2.2)
  * Click on //Fork project//.

//Image 1// {{:tutorials:fork.png?400| Ímage 1}}


//Image 2// {{:tutorials:fork2.png?400|Image 2}}


The fork is optional in order to download the code, but it is recommended if you plan on pushing modification back to the main repository (it keeps the modifications management clean).

==== Add an ssh key to Gitlab ====

To skip the authentication for every git command to your gitlab repository, one way is to add an ssh key from your computer to your gitlab account.

First create an ssh key if you don't already have one, by running the ''ssh-keygen'' command. This should create two files in your /home/.ssh/ folder: id_rsa and id_rsa.pub.

In GitLab go in your profile, then in ssh keys.

{{:tutorials:sshkey1.png?200|}}

  * Click on ''Add key''
  * In the new panel, paste the content of your public key in the corresponding area. The public key is the id_rsa**.pub**. You should NEVER share the other one ( the private key). On windows to open the file you can right click on it, open with, text editor.

{{:tutorials:sshkey2.png?300|}}

  * Once it is done you can click on ''Add key''

Open a terminal (git bash/or power shell on windows) and go to your working directory (Where GroIMP is going to be downloaded).
You can now clone the git repository on your computer with the simple git command:
<code>
git clone git@gitlab.com:YOURUSERNAME/groimp.git
</code>

Where YOURUSERNAME is your GitLab user name (e.g. git@gitlab.com:gaetan.heidsieck/groimp.git is a valid repo).

If you didn't set up your ssh key you can use:
<code>
git clone https://gitlab.com/YOURUSERNAME/groimp.git
</code>

If you didn't fork you can clone from the main repo:
<code>
git clone git@gitlab.com:grogra/groimp.git
</code>

You should have a directory called groimp with all the content of the core repository.

===== Use Maven to compile =====

Now that we have the source code in a local directory, we can compile (or even package) it. To do so, move the terminal (git bash/or power shell on windows) to the groimp directory (with ''cd groimp'' for instance).
Then, use the maven command: ''mvn package''. 
This should create a folder called **app** in the current directory. This app folder is where compiled GroIMP plugins goes in the format ready to be shared. In it there is a platform-core....jar file. You can start groimp by starting this jar. (either double click on Windows, or from the terminal ''java -jar platform.....jar'').

You will notice however that, with only the core, GroIMP lack most of its features. Even some of the most used like RGG. You could download them using the [[01_user_documentation:user-guide:pluginmanager|plugin manager]], but it would only get the already compiled plugins. Here we will download them from GitLab and compile them from scratch.

==== Add other plugins to the command ====

set your terminal in the main groimp directory (the one you used mvn package in) and download the two plugins [[https://gitlab.com/grogra/groimp-plugins/GPUFlux|GPUFlux]] and [[https://gitlab.com/grogra/groimp-plugins/RGG|RGG]] with the commands:

<code>
git clone git@gitlab.com:grogra/groimp-plugins/GPUFlux.git
git clone git@gitlab.com:grogra/groimp-plugins/RGG.git
</code>

You now have two new directory: GPUFlux and RGG in your groimp directory. They are not yet included in the maven commands though. 
To include them in the build from the groimp directory (the parent pom), you need to modify that pom.xml file.
on the bottom of the file in the <modules> section, add the two <module>GPUFlux</module> and <module>RGG</module>. Notice that the names used is the directory name, not the java one.

Now the command ''mvn package'' will add the two additional plugin to the compiled plugins.

==== Compile individual plugins ====

If you do not want to download the source of the whole GroIMP core and some additional plugins, you can compile plugins alone. The core, and other plugin dependencies can be retrieved by Maven.
For Maven to be able to download package from the GroIMP git repository, it requires to be set up.

First, create a file called ''settings.xml'' file under your ''.m2'' directory (the maven directory, usually in ~/.m2 or /home/.m2). Add the following content:

<code xml>
<settings xmlns="http://maven.apache.org/SETTINGS/1.1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.1.0 http://maven.apache.org/xsd/settings-1.1.0.xsd">
  <servers>
     <server>
       <id>gitlab-maven</id>
       <configuration>
         <httpHeaders>
           <property>
             <name>Private-Token</name>
             <value>XXXXXXXXXXXXXX</value>
           </property>
         </httpHeaders>
       </configuration>
     </server>
   </servers>
 </settings>
</code>

Then, get your private token. In gitlab under profile>preference>personal token, create a new personal token. The name does not matter. Add the right to read registry as a minimum right. Be sure to set the token after creation as you cannot retrieve it latter. Change the XXXXXXXXXXXXXX in the settings.xml file with your personal token.

You can now go in the directory of any GroIMP plugin (go in the RGG directory for instance) and compile it (With '' mvn compile'' or ''mvn package''). Maven will then download by itself all the required dependencies, including GroIMP plugins.

===== Set up Eclipse =====

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

Now that we have the source code of the plugin(s) we want to modify, we can import it in Eclipse.

Open Eclipse 

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

Open the category `Maven`.

Select `Existing Maven Projects`.

Set the Root Directory as either a specific plugin directory, or as the groimp repository you downloaded.

All GroIMP plugins in that directory 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 resources 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 [[01_user_documentation:user-guide:advanced-groimp-arguments| GroIMP additional arguments]] for more information on the most common arguments you can change when running GroIMP.