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.
===== Compile a GroIMP plugin =====

==== Requirements ====

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

It is possible to compile and package one specific plugin. The plugin has to follow the template of [[https://gitlab.com/grogra/groimp-template/newplugin-maven|new plugin]]. 

The template contains:

  - The assembly folder used to package the plugin with its dependency into a folder. Maven dependencies are automatically packaged. Third party local jars are also automatically included if the local-repository is setup in the plugin pom.xml file, and the maven property ''<maven.assembly.plugin.move-lib>generate-resources</maven.assembly.plugin.move-lib>'' is set.
  - The pom.xml that contains: the repository _gitlab-maven_ that points at this repository of maven artifacts, the parent dependency to de.grogra.GroIMP, which automatically loads some required dependencies.

Then, the plugin can be compiled with ''mvn compile'', or packaged with ''mvn package''. The packaging creates a repository at ../app/plugin/NAME_OF_YOUR_PLUGIN based on the root of the plugin. This repository can be added to an existing installation of GroIMP by simple copy and paste. 
 
==== Compile with help panels ====

The documentation inside GroIMP is written in docbook, which can be compiled into the html layout seen in the help panel. 
To do this compilation an installation of docbook, docbook-xsl and xsltproc  is required. 
On a Debian based system these can be installed with the following command: 
''sudo apt install xsltproc docbook docbook-xsl''

This requires to have ''pandoc'' version > 3.3 installed on your device. 

Afterwards the maven command: ''mvn package -P app-with-doc'' can be executed.



===== Compile the complete project: =====

To compile a set of GroIMP plugins (i.e. for a release), the parent pom.xml file of GroIMP is required. This file is a maven reactor file, which defines the list of plugins (maven modules) that should be compiled. 

The easiest setup is to have all plugins and this parent pom in one repository. Then, make sure the parent pom.xml module list contains the exact set of plugins to compile. 

It is then possible to apply maven commands to the reactor: 
  - ''mvn compile'' will compile each plugin into their own directory under target/classes
  - ''mvn package'' will compile and package each plugin into a newly created app/ directory. The packaging includes the dependencies of each plugin, as well as all resources required for the execution. If the module includes the core GroIMP packages (XL-Core, Utilities, Graph, Platform-Core), then their compiled classes are merged into a core.jar file at the root of app/

===== Compile the documentation =====

GroIMP plugins can include documentation that is compiled and embedded in the GroIMP platform (accessible through the Help menu). This documentation is automatically compiled and packaged with maven if it follow the template: the documentation is under src/main/resources/doc/ and the entry point of this documentation is a file called manual.xml.

The java documentation of a specific plugin can be compiled with ''mvn javadoc'' within the plugin repository. The documentation is created in the target folder of the plugin.

To compile the java documentation of a set of GroIMP plugins and packages, at the root use
''mvn package javadoc:aggregate'' to produce the complete javadoc under the target/ folder.
It is required to package before aggregating the javadoc because javadoc:aggregate only considers named java modules, and some GroIMP plugins are unnamed java modules. Their automatic naming is associated with files created during the packaging.

===== Create the executable release files ======

Once the desired plugins and core packages are packaged with maven it is possible to create executable files to install GroIMP for Windows, Debian and MacOS. 

This operation requires an additional GroIMP plugin: [[https://gitlab.com/grogra/groimp-plugins/build|Build]].
Put the Build plugin at the root of the GroIMP parent pom.xml. Make sure that the packaged classes and jars are under app/, app/core.jar, and app/plugins/. 

The command ''mvn package -P release'' will create the three files for installation.

A specific distribution can be selected with ''mvn package -P release-win'' ''mvn package -P release-deb'', or ''mvn package -P release-macos'' to create a single executable.

See more:

  * [[:dev-guide:maven-commands|List of useful Maven commands]]
===== Deploy the release files online =====

The executable files can be added to the [[https://gitlab.com/grogra/groimp-releases|release files]] on gitlab, then linked to a release under gitlab create new release menu.

===== Deploy the new version of the maven artifacts on gitlab =====

The GroIMP sources, and plugins are available as maven artifacts (accessible with the repository gitlab-maven defined as in the template file). 

The update of these artifacts is automatically handled by a gitlab pipeline. The pipeline starts when a new gitlab tag is created on the master branch.