Skip to content

Developing Plugins

Baptiste Lesquoy edited this page May 28, 2023 · 2 revisions

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.

  1. From the Eclipse main menu tab, click on File, then New, then Project, then finally select plug-in project. Annotation 2023-04-14 051051_fileNPP

  2. In the "New plug-in Project" / "Plug-in project" window:

    1. Choose as name « name_of_the_plugin » (or anything else)*
    2. Check "Use defaut location"
    3. Check "Create a Java Project"
    4. The project should be targeted to run with Eclipse
    5. working set is unchecked
    6. Click on "Next"

    Annotation 2023-04-13 1300361_NewPlug_0

  3. In the "New plug-in Project" / "Content" window:

    1. Id : could contain the name of your institution and/or your project, e.g. « irit.maelia.gaml.additions »
    2. version 1.0.0.qualifier (this latter mention is important if you plan on distributing the plugin on GAMA update site)
    3. Name «This is my First Plugin.»
    4. Uncheck "Generate an activator, a Java class that controls the plug-in's life cycle" ,
    5. Uncheck "This plug-in will make contributions to the UI"
    6. Check "No" when it asks "Would you like to create a rich client application ?"
    7. Click on "Next"

    Annotation 2023-04-13 125516_NewPluginProject_1

  4. In the "New plug-in Project" / "Templates" window:

    1. Uncheck "Create a plug-in using one of the templates"
    2. Click on "Finish"

    Annotation 2023-04-13 125838_NewPluginProject_2

    1. Your plug-in has been created.
  5. Edit the file "Manifest.MF":

    1. From the Project Explorer pane, expand your plugin folder.
    2. Click on the META-INF folder.
    3. Click on the MANIFEST.MF file.

    Annotation 2023-04-13 171044_manifest_drawoverlays

    1. Click on the Overview tab to open the Overview pane:

    2. On the Overview pane, check as shown « This plug-in is a singleton »

    3. Dependencies pane:

      1. Click on the Dependencies tab to open the Dependencies Pane.

      Annotation 2023-04-13 172748_dependenciesPane

      1. add (at least minimum) the two plug-ins "msi.gama.core" and "msi.gama.ext" in the "Required Plug-ins". When you click on "Add", a new window will appear without any plug-in. Just write the beginning of the plug-in name in the text field under "Select a plug-in"

      Annotation 2023-04-13 173511_dependenciesAnnotation

    4. Click on the Runtime tab to open the Runtime pane:

      Annotation 2023-04-13 180418_runtime

      1. In exported Packages: nothing (but when you will have implemented new packages in the plug-in you should add them there)
      2. Add in the classpath all the additional libraries (.jar files) used in the project.
    5. Click on the Extension tab to open the Extensions pane:

      • Click the Add button and add "gaml.extension"

    Annotation 2023-04-13 183311_extensions

  6. On the main menu, click on File, then select, Save, to save the file. This should create a "plugin.xml" file.

Annotation 2023-04-13 183950_pluginXML

  1. In the Project Explorer pane, Select the plugin, right_click, and in the dropdown menu select Properties:

    Annotation 2023-04-13 184528_properties

    1. The Properties for myFIrstPlugin dialog opens as shown.

    Annotation 2023-04-13 190352_annotationProcessing

    1. In the Properties dialog .. Go to Java Compiler, then Annotation Processing: check "Enable project specific settings", then in "Generated Source Directory", change ".apt_generated" to "gaml",

    Annotation 2023-04-13 191019_agamlAnnotation

    1. Go again to Java Compiler, then Annotation Processing, then Factory path: check "Enable project specific settings", then "Add Jars" and choose "msi.gama.processor/processor/plugins/msi.gama.processor.1.4.0.jar"

    Annotation 2023-04-13 192132_factoryPath

    1. Close the menu. Click on Yes in the succeeding dialogs (Annotation settings changed ..). After, this should compile the project and create the gaml directory.

    Annotation 2023-04-13 193119_annotationChangeStop

  2. Return to the Properties dialog of your plugin by clicking from the main menu bar, Project, then click on Properties. Go to Java Build Path, click on the Source Tab, and check that the gaml directory has been added. Annotation 2023-04-14 044959_propertiesCheck

  3. If the gaml folder is not present, click on Add Folder and select the gaml directory. Right click on the project, then refresh it (F5 or from the File menu -> Refresh)

Annotation 2023-04-14 045929_refresh

  1. Now, there should be a gaml directory. This gaml directory will later contain the package containing GamlAdditions.java, and other related files created after creating classes. If there is no package in the folder, try creating a class, then try to refresh or close the project and reopen it, or clean the projects by going into Project tabs, and clicking on clean.

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 adds this feature to the existing product (or a new .product file of your own).

The use of feature 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 gather 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 detailled steps to create and configure a new feature.

  • File > New > Feature project (or File > New > Project... then Plug-in Development > Feature Project)
  • In Feature properties
    • Choose a project name (e.g. "institution.gama.feature.pluginsName")
    • Click on "Next"
  • 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"
  • 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"
      • In the Plug-ins and Fragments, additional plug-ins can be added.

Addition of a feature to the product

To load the plugin into GAMA, go into the project ummisco.gama.product and open gama.product 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 Configuration, then you should have the gama runtime product window open, click on the plugins tab, and check your plugin in the list. Click on Apply. Now your plugin is accessible in GAMA, now 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 ummisco.gama.product project:

  • Contents pane
    • Click on Add button
    • In the window select the feature
    • Click on OK.

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

Hence this is done, you can update 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

a/ Add pom.xml for plugin institution.gama.pluginsName:

  • Right click -> Configure -> Convert to maven project to add pom.xml:
  • Set:
    • 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.qualifier
    • Packaging: eclipse-plugin // this element is not in the list (jar/pom/war) because of the incompatible of tycho, maven and eclipse, so just type it in although it will be a warning
  • Finish

b/ Configure pom.xml to recognize the parent pom.xml for Maven builds

  • Open pom.xml in institution.gama.pluginsName
  • Tab overview, Parent section, type in:
    • Group id: msi.gama
    • Artifact id: msi.gama.experimental.parent
    • Version: 1.7.0-SNAPSHOT
    • Relative path: ../msi.gama.experimental.parent
  • Save

c/ 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 context menu or use Quick Fix."

  • Right click -> Maven -> Update project

Create a feature for the plugin

a/ Create new feature

  • New -> Project -> type in : feature -> Select "Feature Project"
  • Set:
    • Project name: institution.gama.feature.pluginsName
    • Uncheck use default location, type in: {current git repository}\aaa.bbb.feature.ccc
    • Feature Version: 1.0.0.qualifier
    • Update Site URL: http://updates.gama-platform.org/experimental
    • Update Site Name: GAMA 1.7.x Experimental Plugins Update Site
  • Click Next
    • Initialize from the plugin list -> check all plugins needed: institution.gama.pluginsName (1.0.0.qualifier)
  • Finish

b/ Add pom.xml for feature institution.gama.feature.pluginsName:

  • Right click -> Configure -> Convert to maven project (to add pom.xml)
  • Set:
    • Group id: institution.gama.feature.pluginsName
    • Artifact id: institution.gama.feature.pluginsName
    • Version: 1.0.0-SNAPSHOT
    • Packaging: eclipse-feature
  • Finish

c/ Configure pom.xml to recognize the parent pom.xml for Maven builds

  • Open pom.xml in institution.gama.pluginsName
  • Tab overview, Parent section, type in:
    • Group id: msi.gama
    • Artifact id: msi.gama.experimental.parent
    • Version: 1.7.0-SNAPSHOT
    • Relative path: ../msi.gama.experimental.parent
  • Save

d/ 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 context menu or use Quick Fix."

  • Right click -> Maven -> Update project

Update p2updatesite category.xml (this step will be done automatically by travis, soon)

Open msi.gama.experimental.p2updatesite

  • Tab Managing the Categories -> Add feature -> institution.gama.feature.pluginsName

How to make a plug-in available as an extension for the GAMA release (obsolete)

Once the plug-in has been tested in the GAMA SVN version, it can be made available for GAMA release users.

First, the update_site should be checked out from the SVN repository:

  • File > New > Other... > SVN > Project from SVN
  • In Checkout Project from SVN repository
    • Use existing repository location (it is the same location as for the GAMA code)
    • Next
  • In Select resource:
    • Browse
      • choose svn > update_site
    • Finish
  • Finish

Now the update_site project is available in the project list (in Package Explorer). The sequel describes how to add a new feature to the update site.

  • Open the site.xml file
  • In update site Map:
    • Click on Extensions
    • click on the Add Feature... button
      • Choose the feature to be added
      • It should appear in Extensions
    • Select the added feature and click on the Synchronize... button
      • Check Synchronize selected features only
      • Finish
    • Select the added feature and click on the Build button
  • All the files and folder of the update_site project have been modified.
  • Commit all the modifications on the SVN repository
    • Richt-click on the project, Team > Update
    • Richt-click on the project, Team > Commit...

The plug-in is now available as an extension from the GAMA release. More details about the update of the GAMA release are available on the dedicated page.

  1. What's new (Changelog)
  1. Installation and Launching
    1. Installation
    2. Launching GAMA
    3. Updating GAMA
    4. Installing Plugins
  2. Workspace, Projects and Models
    1. Navigating in the Workspace
    2. Changing Workspace
    3. Importing Models
  3. Editing Models
    1. GAML Editor (Generalities)
    2. GAML Editor Tools
    3. Validation of Models
  4. Running Experiments
    1. Launching Experiments
    2. Experiments User interface
    3. Controls of experiments
    4. Parameters view
    5. Inspectors and monitors
    6. Displays
    7. Batch Specific UI
    8. Errors View
  5. Running Headless
    1. Headless Batch
    2. Headless Server
    3. Headless Legacy
  6. Preferences
  7. Troubleshooting
  1. Introduction
    1. Start with GAML
    2. Organization of a Model
    3. Basic programming concepts in GAML
  2. Manipulate basic Species
  3. Global Species
    1. Regular Species
    2. Defining Actions and Behaviors
    3. Interaction between Agents
    4. Attaching Skills
    5. Inheritance
  4. Defining Advanced Species
    1. Grid Species
    2. Graph Species
    3. Mirror Species
    4. Multi-Level Architecture
  5. Defining GUI Experiment
    1. Defining Parameters
    2. Defining Displays Generalities
    3. Defining 3D Displays
    4. Defining Charts
    5. Defining Monitors and Inspectors
    6. Defining Export files
    7. Defining User Interaction
  6. Exploring Models
    1. Run Several Simulations
    2. Batch Experiments
    3. Exploration Methods
  7. Optimizing Model Section
    1. Runtime Concepts
    2. Optimizing Models
  8. Multi-Paradigm Modeling
    1. Control Architecture
    2. Defining Differential Equations
  1. Manipulate OSM Data
  2. Diffusion
  3. Using Database
  4. Using FIPA ACL
  5. Using BDI with BEN
  6. Using Driving Skill
  7. Manipulate dates
  8. Manipulate lights
  9. Using comodel
  10. Save and restore Simulations
  11. Using network
  12. Headless mode
  13. Using Headless
  14. Writing Unit Tests
  15. Ensure model's reproducibility
  16. Going further with extensions
    1. Calling R
    2. Using Graphical Editor
    3. Using Git from GAMA
  1. Built-in Species
  2. Built-in Skills
  3. Built-in Architecture
  4. Statements
  5. Data Type
  6. File Type
  7. Expressions
    1. Literals
    2. Units and Constants
    3. Pseudo Variables
    4. Variables And Attributes
    5. Operators [A-A]
    6. Operators [B-C]
    7. Operators [D-H]
    8. Operators [I-M]
    9. Operators [N-R]
    10. Operators [S-Z]
  8. Exhaustive list of GAMA Keywords
  1. Installing the GIT version
  2. Developing Extensions
    1. Developing Plugins
    2. Developing Skills
    3. Developing Statements
    4. Developing Operators
    5. Developing Types
    6. Developing Species
    7. Developing Control Architectures
    8. Index of annotations
  3. Introduction to GAMA Java API
    1. Architecture of GAMA
    2. IScope
  4. Using GAMA flags
  5. Creating a release of GAMA
  6. Documentation generation

  1. Predator Prey
  2. Road Traffic
  3. 3D Tutorial
  4. Incremental Model
  5. Luneray's flu
  6. BDI Agents

  1. Team
  2. Projects using GAMA
  3. Scientific References
  4. Training Sessions

Resources

  1. Videos
  2. Conferences
  3. Code Examples
  4. Pedagogical materials
Clone this wiki locally