Differences

This shows you the differences between two versions of the page.

--- dev-guide:getting-started [2024/06/25 10:17] – created gaetan
+++ dev-guide:getting-started [2024/12/18 10:54] (current) – [Developer Guide] gaetan
@@ Line 1: / Line 1: @@
-===== Developer Guide =====
+====== Developer Guide ======
-Welcome to this developer guide! This guide is written to give new GroIMP developers an overview about how the required development environment is prepared and installed.
+Welcome to this developer guide!
-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.
-  - (Optional) **Forking** the official repository to an own one. This is done to be able to commit and push changes.
-  - (Optional) **Mirroring** the fork repository to the official one. This merges updates of the official repository to the fork repository automatically.
-  - **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.
+Developing on the GroIMP source code only require a java compiler. Additionally GroIMP support two development setup: Maven and Eclipse.
 ==== Requirements ====
-  * Experience with Java and Git
+To compile GroIMP you will need the following additional tools:
-  * A gitlab account on [[ https://gitlab.com | Gitlab]] for cloning in Eclipse (**optional** if the cloning is done without Eclipse).
+  * [[https://maven.apache.org/install.html|Maven]]
-  * Java >= 17
+  * [[https://www.oracle.com/java/technologies/downloads/|Java 17]] or newer
+  * [[https://www.perl.org/get.html|Perl]]
+===== Get the source code =====
+The first step to start developing on the code is to get it. The code is entirely open source and available on [[https://gitlab.com/grogra/]].
-==== Installing Eclipse ====
+The source code is split between the "core" at [[https://gitlab.com/grogra/groimp]] and the plugins at  [[https://gitlab.com/grogra/groimp-plugins]]. It is possible to work separately on the core and the plugins as each are compilable by themselves.
-=== 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>
 ==== (Optional) Forking the repository ====
-Go to [[https://gitlab.com/grogra/groimp]] in your internet browser.
+  * Go to the git repository page in your internet browser.
+  * Click on the //Fork// button of the repository.
-Click on the //Fork// button of the repository.
+  * Select your own gitlab namespace and optionally an other project name (not recommended).
+  * Change or reuse the project slug and description.
-Select your own gitlab namespace and optionally an other project name (not recommended).
+  * Click on //Fork project//.
-Change or reuse the project slug and description.
-Click on //Fork project//.
 ==== (Optional) Mirroring the repository ====
-In an internet browser, go to your own repository that forks the official one.
+  * In an internet browser, go to your own repository that forks the official one.
+  * On the side bar, click on //Settings// > //Repository//.
-On the side bar, click on //Settings// > //Repository//.
+  * Expand the category `Mirroring repositories`.
+  * Insert the URL of the official repository: [[https://gitlab.com/grogra/groimp]] (or the url of the plugin)
-Expand the category `Mirroring repositories`.
+  * Click on //Mirror repository//
+**Note: the two previous steps are optional for users, but highly recommended if you plan on contributing to the code.**
-Insert the URL of the official repository: [[https://gitlab.com/grogra/groimp]]
-Click on //Mirror repository//
-**Note: the two previous steps are optionals for users, but highly recommended if you plan on contributing to the code.**
 ==== Cloning the repository ====
-=== In Eclipse ===
-Click on //File// > //Import...//
-Open the category `Git`
-Select //Projects from Git//
-Click on //Next > //
-Select `Clone URI`
-Click //Next > //
-Insert `git@gitlab.com:yourgitlabprefix/groimp.git` into the URI field and replace the prefix with your prefix where to find the
-forked repository
-The other fields are automatically set.
-Click on //Next > //
-The key information is shown now.
-Select the checkbox `Accept and store this key, and continue connecting?`
-Click on //OK<//
-Now, the branch selection window appears.
-All branches should be selected.
-Click on //Next > //
-Set the local path to the repository. It should be in your user directory in the subdirectory `/home/username/git/groimp/`.
-Click on //Next > //
-This may take much time since the repository is very large (800 MB).
-In the resulting window, click //Next > //
-In the next window, all subprojects must be selected.
-Click on //Finish//
-Wait until it has been built.
-The repository is imported as a long list of projects.
-The repository is imported in Ecplise and you can go to setting Eclipse up.
 === From GitLab ===
@@ Line 153: / Line 42: @@
 It is possible to simply download the directory of source code from GitLab on the main page [[https://gitlab.com/grogra/groimp]]. There is a download arrow button right next to the _clone_ button.
 You can then download the whole repository as any archive format you like.
+Once it is downloaded, extract the archive to the directory in your workspace.
-Once it is downloaded, extract the archive to the directory where you want to setup your eclipse workspace.
-You still need to import the repository in Eclipse. See two section bellow.
 === From a bash command ===
 You can clone a repository from GitLab with the command line:
 <code>
 git clone  https://gitlab.com/grogra/groimp.git
@@ Line 170: / Line 54: @@
 This will create a directory named groimp and download all the remote content in it.
-You still need to import the repository in Eclipse. See the section bellow.
-=== 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.
+===== Compile with Maven =====
-Go to //Run > Run Configurations...//.
+Now that you have the source code on your local device, you can compile it with Maven. Maven require ''pom.xml'' files to process a project.
+GroIMP core have both a parent pom.xml and a pom.xml for each plugins. Additional plugins only have their pom.xml.
+Maven commands are executed from a terminal (bash, Powershell, ...).
+Maven commands can be executed either at the project level (on the parent ''pom.xml'') or at the plugin level (whithin a plugin, at a ''pom.xml'' level). The commands at the project level will propagate to all plugins defined within the parent pom file.
-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.
+The plugins are added with the <module/> tag. You can add or remove plugins to the parent. The plugins are defined with their repository name. Make sure that all the plugins that you want to be included in the commands are listed there.
-Give the starter a good name, for example `GroIMP`.
+The most useful maven commands are:
-Select the project `Platform-Core` if it is not selected automatically.
+  * ''mvn compile'' will compile the code under ''/groimpsourcepath/pluginpath/target/''. In the case where it is executed at the groimp root (for the groimp core), the compiled classes are stored under each plugin/target directory.
+  * ''mvn package'' will compile the code, and package it for deployment. The compiled package is under ''/groimpsourcepath/app/''. It should automatically include dependency jars and resources. The packaged repository can be copied to an other groimp installation.
+  * ''mvn clean'' clean the repository, deleting all ''target'' and ''app'' repositories.
-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.
+If you package the groimp core code, you will have a ''platform-with-dependency.jar'' in the ''/groimpsourcepath/app'' directory. You can start the compiled version of GroIMP with
+'' java -jar platform-with-dependency.jar''.
-Then, click on //Apply// and go to the tab `x() = Arguments`.
+==== Common errors ====
-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".
+The maven commands can fail, here are some common errors:
+  * ''The goal you specified required a project to execute but there is no POM in this directory ... ''. This happens when you execute the maven commands in a directory without a proper pom file. You might not be in the correct directory, or the git clone commands may have failed. Make sure you have a pom.xml file in the current directory when executing a maven command
+  * ''Child module /some/path/PLUGINNAME of ... /some/other/path/pom.xml does not exist @''. This happens when using the parent pom.xml. It means that one GroIMP plugin is defined in the <module> list of the plugins. However, that plugin is not found on the local directory. Make sure you remove all ''<module>'' elements from the parent pom.xml that are not present on your local installation.
+  * ''Could not resolve dependencies for project xx.xx:version''. This happens when one plugin depends on a dependency that cannot be reached. Either the dependency is not released yet (it can happens with groimp plugins) or the maven repository requested is unavailable.
-For the JVM arguments, add `-Xmx3000m`. If required, more or less memory can be specified here instead of 3000 MB.
+===== Eclipse =====
-Check [[:User-Guide:Advanced-GroIMP-arguments | GroIMP additional arguments]] for more information on the most common arguments you can change when running GroIMP.
+See the guide on how to setup your Eclipse environment [[:dev-guide:developer-guide| here]].