Developing Plugins - gama-platform/gama GitHub Wiki
Developing Plugins
This page details how to create a new plug-in in order to extend the GAML language with new skills, species, displays or operators. It also details how to create a plug-in that can be uploaded on an update site and can be installed into the GAMA release. We consider here that the developer version of GAMA has been installed (as detailled in this page).
I. Creation of a plug-in
Here are detailed steps to create and configure a new GAMA plug-in.
-
From the Eclipse main menu tab, click on
File
, thenNew
, thenProject
, then finally selectplug-in project
. -
In the
New plug-in Project
/Plug-in project
window:- Choose as
name
the name of your plugin - Check
Use default location
- Check
Create a Java Project
- The project should be
targeted to run with
Eclipse
working set
is unchecked- Click on
Next
- Choose as
-
In the
New plug-in Project
/Content
window:ID
: could contain the name of your institution and/or your project, e.g.irit.maelia.gaml.additions
Version
:1.0.0.qualifier
(this latter mention is important if you plan on distributing the plugin on GAMA update site)Name
:This is my First Plugin.
- Uncheck
Generate an activator
, a Java class that controls the plug-in's life cycle. - Uncheck
This plug-in will make contributions to the UI
- Check
No
when it asks if you would like tocreate a rich client application?
- Click on
Next
-
In the
New plug-in Project
/Templates
window:- Uncheck
Create a plug-in using a template
- Click on
Finish
- Your plug-in has been created.
- Uncheck
-
Edit the file
Manifest.MF
:- From the Project Explorer pane, expand your plugin folder.
- Click on the
META-INF
folder. - Click on the
MANIFEST.MF
file.
-
Click on the
Overview
tab to open the Overview pane: -
Check as shown
This plug-in is a singleton
-
Dependencies pane:
- Click on the
Dependencies
.
- add (at least) the two plug-ins
gama.core
andgama.dependencies
in theRequired Plug-ins
. When you click onAdd
, a new window will appear without any plug-in. Just write the beginning of the plug-in name in the text field underSelect a plug-in
- Click on the
-
Click on the
Runtime
tab to open the Runtime pane:- In
Exported Packages
: nothing (but when you will have implemented new packages in the plug-in you should add them there) - Add in the
Classpath
all the additional libraries (.jar
files) used in the project.
- In
-
Click on the
Extensions
tab to open the Extensions pane:- Click the
Add...
button and addgaml.extension
- Click the
-
On the main menu, click on
File
, then selectSave
, to save the file. This should create aplugin.xml
file.
-
In the Project Explorer view, select the plugin, right click on it, and in the contextual menu select
Properties
:- The Properties dialog for your plugin opens as shown.
- In the
Properties
dialog, go toJava Compiler
, thenAnnotation Processing
: checkEnable project specific settings
, then inGenerated Source Directory
, change.apt\_generated
togaml
,
- Go again to
Java Compiler
, thenAnnotation Processing
, thenFactory path
: checkEnable project specific settings
, thenAdd Jars
and choosegama.processor/gama.processor.1.4.0.jar
- Close the menu. Click on
Yes
in the succeeding dialogs (Annotation settings changed ...). After, this should compile the project and create thegaml
directory.
-
Return to the
Properties
dialog of your plugin by clicking from the main menu bar,Project
, then click onProperties
. Go toJava Build Path
, click on theSource
Tab, and check that thegaml
directory has been added. -
If the
gaml
folder is not present, click onAdd Folder...
and select thegaml
directory. Right click on the project, then refresh it (F5
or from theFile
menu ->Refresh
)
- Now, there should be a
gaml
directory. This gaml directory will later contain the package containingGamlAdditions.java
, and other related files generated after creating classes. If there is no package in the folder, try creating a class, then try torefresh
orclose
the project and reopen it, orclean
the projects by going intoProject
tabs, and clicking onclean
.
The plug-in is ready to accept any addition to the GAML language, e.g. skills, actions, operators. To proceed to creating a skill click on this link.
Do not forget to export the created packages that could be used by "clients", especially the packages containing the code of the additions (in the plugin.xml
of the new project, tab Runtime
).
To test the plug-in and use it into GAMA, developers have to define a new feature project containing your plugin and its dependencies, and add this feature to the existing gama.product
file (or a new .product
file of your own).
The use of feature project is also mandatory to define a plug-in that can be uploaded on the update site and can be installed in the release of GAMA.
Creation of a feature
A feature is an Eclipse project dedicated to gathering one or several plug-ins to integrate them into a product or to deploy them on the update site and install them from the GAMA release (a feature is mandatory in this case).
Here are detailed steps to create and configure a new feature.
File
>New
>Feature project
(orFile
>New
>Project...
thenPlug-in Development
>Feature Project
)- In
Feature properties
- Choose a project name (e.g.
institution.gama.feature.pluginsName
) - Click on
Next
- Choose a project name (e.g.
- In Referenced Plug-ins and fragments
- Check
Initialize from the plug-ins list:
- Choose the plug-ins that have to be gathered in the feature
- Click on
Finish
- Check
- A new project has been created. The
feature.xml
file will configure the feature.- In
Information pane
:- You can add description of the various plug-ins of the feature, define the copyright notice and the licence.
- In
Plug-ins and Fragments
- additional plug-ins can be added.
- In
Addition of a feature to the product
To load the plugin into GAMA, go into the project gama.product
open the gama.product
file and go into the overview tab, under the section Testing
, click Synchronize
, go into the Contents
tab, click on Add...
, and add the features related to your plugin. Click the Run
tab in the main menu bar, click on Run Configurations...
, then you should have the gama runtime product window open, click on the Plug-ins
tab, and check the box next to your plugin in the list. Click on Apply
. Now that your plugin is accessible in GAMA, we can run the application. Click on Run
.
Remark: To check whether the new plug-in has been taken into account by GAMA, after GAMA launch, it should appear in the Eclipse console in a line beginning by >> GAMA bundle loaded in
.
If you plan to deploy your plugin to be used by other users from the GAMA community, proceed with the succeeding steps. If not, we can proceed with the creation of skills and types.
In the product, e.g. gama.product
in the gama.product
project:
- go to
Contents
pane- Click on
Add...
button - In the window select the feature
- Click on
OK
.
- Click on
Create examples model
In order to make your plugin usable by everyone, it is very important to bring potential users model examples to introduce new gaml primitives, statements and operators. This way, modelers can easily get into the plugin you developed in a practical way.
The process is twofold:
- Mount your plugin into your GAMA (see below or use the
git
version) - Create a new project in the user model folder. Put your GAMA model examples there.
- Move your project into a folder called
models
at the root of the plugin
Once this is done, you can refresh your Plugin models
library folder and have access to the plugin models
How to make a plug-in available at GAMA update site for the GAMA release
Considering a working GAMA plugin named institution.gama.pluginsName
Configure plugin to be available for Maven
pom.xml
for plugin institution.gama.pluginsName
:
Add - Right click on the project->
Configure
->Convert to maven project
. - In the dialog that opened, set the values as this:
Group id
:institution.gama.pluginsName
Artifact id
:institution.gama.pluginsName
Version
:1.0.0-SNAPSHOT
, must have -SNAPSHOT if the plugin version is x.x.x.qualifierPackaging
:eclipse-plugin
. This element is not in the list (jar/pom/war) because of the incompatible oftycho
,maven
andeclipse
, so just type it in although it will be a warning
Finish
pom.xml
to recognize the parent pom.xml
for Maven builds
Configure - Open
pom.xml
ininstitution.gama.pluginsName
- In the tab
Overview
,Parent
section, type in:Group id
:org.gama
Artifact id
:gama.experimental.parent
Version
:2024-07-SNAPSHOT
replace by the gama version you want your plugin to be deployed for, followed by-SNAPSHOT
Relative path
:../gama.experimental.parent
- Save
Update maven cache in eclipse (optional)
It will fix this compilation error Project configuration is not up-to-date with pom.xml
. Right click on the project and in the contextual menu select: Maven
->Update Project...
or use Quick Fix
.
Create a feature for the plugin
Create new feature
New
->Project
-> type in :feature
-> SelectFeature Project
- Set:
Project name
:institution.gama.feature.pluginsName
- Uncheck
use default location
, type in:{current git repository}\institution.gama.feature.pluginsName
Feature Version
:1.0.0.qualifier
- Click
Next
Initialize from the plugin list
-> check all plugins needed:institution.gama.pluginsName (1.0.0.qualifier)
Finish
- Open
feature.xml
, in the tabOverview
, in theGeneral Information
section type in:Update Site URL
:http://updates.gama-platform.org/experimental
Update Site Name
:GAMA Experimental Plugins Update Site
pom.xml
for feature institution.gama.feature.pluginsName
:
Add - Right click on the feature project ->
Configure
->Convert to maven project
- Set:
Group id
:institution.gama.feature.pluginsName
Artifact id
:institution.gama.feature.pluginsName
Version
:1.0.0-SNAPSHOT
Packaging
:eclipse-feature
Finish
pom.xml
to recognize the parent pom.xml
for Maven builds
Configure - Open
pom.xml
in the projectinstitution.gama.pluginsName
- In the
Overview
section in the tabParent
type in:Group id
:org.gama
Artifact id
:gama.experimental.parent
Version
:2024-07-SNAPSHOT
replace by the gama version you want your plugin to be deployed for, followed by-SNAPSHOT
Relative path
:../gama.experimental.parent
Save
Update maven cache in eclipse (optional)
It will fix this compilation error Project configuration is not up-to-date with pom.xml
. Select: Maven
->Update Project...
from the project contextual menu or use Quick Fix
.
Update p2updatesite
- Open
gama.experimental.p2updatesite
- Tab
Managing the Categories
->Add feature
->institution.gama.feature.pluginsName