Differences

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

--- dev-guide:getting-started [2024/06/25 10:51] – [Developer Guide] gaetan
+++ dev-guide:getting-started [2024/12/18 10:54] (current) – [Developer Guide] gaetan
@@ Line 5: / Line 5: @@
 Developing on the GroIMP source code only require a java compiler. Additionally GroIMP support two development setup: Maven and Eclipse.
-  - (Optional) **Forking** the official repository to an own one. This is done to be able to commit and push changes.
+==== Requirements ====
-  - (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)
+To compile GroIMP you will need the following additional tools:
+  * [[https://maven.apache.org/install.html|Maven]]
+  * [[https://www.oracle.com/java/technologies/downloads/|Java 17]] or newer
+  * [[https://www.perl.org/get.html|Perl]]
+===== Get the source code =====
-==== (Optional) Forking the repository ====
+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/]].
-Go to [[https://gitlab.com/grogra/groimp]] in your internet browser.
+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.
-Click on the //Fork// button of the repository.
-Select your own gitlab namespace and optionally an other project name (not recommended).
+==== (Optional) Forking the repository ====
-Change or reuse the project slug and description.
+  * Go to the git repository page in your internet browser.
+  * Click on the //Fork// button of the repository.
-Click on //Fork project//.
+  * Select your own gitlab namespace and optionally an other project name (not recommended).
+  * 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 ====
 === From GitLab ===
@@ Line 44: / 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 61: / 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`.
-=== 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…
+===== Compile with Maven =====
-Open the category `Git`
+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.
-Select Projects from Git
+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.
-Select `Clone URI`
+The most useful maven commands are:
-Insert `git@gitlab.com:yourgitlabprefix/groimp.git` into the URI field and replace the prefix with your prefix where to find the forked repository.
+  * ''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.
-===== Maven =====
+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''.
+==== Common errors ====
+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.
 ===== Eclipse =====
 See the guide on how to setup your Eclipse environment [[:dev-guide:developer-guide| here]].