# Plugin Manager

Sebastian Rodriguez

email: sebastian.rodriguez@utbm.fr

## Contents

- What is it?
- Installing Plugins
  - Upgrading your plugins
- Developers
  - Categories?
  - Ant Build file
  - Adding actions to your plugins
    - DocRef
- Troubleshooting

# What is it?

The plugin Manager keeps track of the installed plugins to make it easier to upgrade your system. It also lets you install only those plugins that you want. It will download the plugin, remove the old version and, finally, install the new one.

# Installing Plugins

You can also install madkit with the plugin manager. There are two way to install madkit with the plugin manger, from the network, via http, and from your local system. The advantage of installing madkit with the plugin manager is that it keeps track of plugins you installed and their versions. With this information upgrading your madkit installation is just a few clicks away. You can also install only the plugins that you need.

Here is a small step by step description to install madkit

- Get a copy of the installer version, usually named plugininstaller-x.y.z.zip. Where x.y.z is the plugin installer's version.

- Run the installer

  $ unzip plugininstaller-x.y.z.zip
  $ cd plugininstaller-x.y.z

  Then run the script to launch the installer, either plugininstaller.sh or madkit-install.exe
  The installer will show you the GPL license and ask you to select the installation directory.
  Then click "Done".
  You will see a window asking for you name and email. IMPORTANT: This information will be sent to the Download Source as your username (your name) and password (your email).
  If you are behind a proxy you can also enter the information here. Please use only the server's name: proxy.yourdomain.com and not http://proxy.yourdomain.com.

  Once you accept, will see the plugin manager window. You can always change your information in "Settings" -> "Options" -> "Settings"

- As I mentioned, here you have to different possibilities:
  1. From the network:
     - Set the download server. You need to download the available plugins list from a server. To set the server's address you can click on Settings -> Options -> Change Download Server

     - Download the plugins list. Click on Settings -> Update Plugin List.
       This will download the plugin list from the server and show you all the available plugins.

       The plugins are divided into categories to make them easier to find. Click on the tabs to change the category. You can find a small description about the categories here

  2. From your local system:
  - First you need to download the full madkit bundle from www.madkit.org
  - Then go to Tools -> Install From local system -> Full Madkit Bundle, this will open a file selection box where you can choose the full madkit bundle zip file. Notice that the plugin manager will copy the plugins into a local repository, so you don't have to install all the plugins.
- Select the plugins you want to install.

  To select a plugin just click on the checkbox on the right of each plugin, don't worry about dependencies, the plugin manager will select them for you. Some "Bundle packages" exist so you don't have to click all plugins one by one.

  If you want a full install, select madkit-full in the Bundle category.

  You can see a small description of a plugin by selecting the plugin and clicking on "Details".

  Note : If you want a default configuration for the madkit Desktop, select desktop2-commons.

- Install. When you are done selecting plugins. Simply click on "Install", the plugin manager will download all the selected plugins and install them. The next time you launch the plugin manager you will find all the installed plugins as "Up to date" or "Needs Update" is a new version is available.

## Upgrading your plugins

Note: This section is only valid if you installed madkit from the network

When you want to check if a new release is available, click on Settings -> Update Plugin List. And then look plugins where the status in shown as "Needs Update".You can also directly click on "Upgrade" and let the plugin manager select the plugins that need an update. Finally click on "install"

# Developers

##
Categories?

The plugin manager divides the plugins into categories. These categories are only used to show the plugins in a more order manner to the user and have no direct effect over the plugin it self. It can even change in the future.
For the moment the following categories exist:

Sources
  contains only the plugins sources packages
Docs
  Contains the plugin's documentations and, in the future, tutorials, technical papers, etc.
Bundle
  Contains some bundle packages. Bundle packages are not plugins, but empty packages that depend on a set of plugins to make it easier to install. For instance, Madkit-full provides a full install of madkit.
demos
  Contains Madkit demo plugins.
utils
  utility plugins (e.g. plugin manager)
main
  Contains the most important plugins in madkit, for example the Madkit Kernel plugin.
Turtlekit
  TurtleKit is a development environment for building simple reactive agents. Loosely based on StarLogo.
Warbot
  Warbot is a test bench for analyzing multi-agent coordination in a robot-like simulated war.

## Ant Build file

Ant will generate for you all needed information to include your plugin in the "web distribution". Your plugin will be separated into three different packages: a binary package, a source package and a documentation package.

Binary
  It includes all necessary files to ensure the proper execution of your plugin. (jar file, scripts etc.)
Source
  Contains your plugin sources. (includes only the src directory)
Documentation
  Contains the plugin's documentation as generated by the "doc" target

Properties used to generate the plugins packages:

project.name name of your plugin.

project.category It places your plugin to the specified category. If it is not defined your plugin will fall into the "unknown" category. This category is used only as a reference to make the plugin easier to find and its only used for the binary package. The source and documentation are in the "sources" and "docs" categories respectively.

depend: probably the most important property, here you define on which plugins your plugin depends on. It is a list of comma separated plugin names.

<property name="depend" value="madkitkernel, pythonlib"/>

zip.extra.inc.bin and zip.extra.inc.prefix if you need to and more than one jar file to your binary package, you can define these to properties. The first one is the jar file to include and zip.extra.inc.prefix is the prefix to use in the zip file. For example:

    	<target name="web-dist" depends="jar">

    		<property name="zip.extra.inc.bin" value="boot.jar"/>

    		<property name="zip.extra.inc.bin.prefix" value="lib"/>

    		<ant antfile="${generic.file}" dir="." target="web-dist" inheritrefs="true"/>

    	</target>

## Adding actions to your plugin

The plugin manager lets you also specify certain action to configure your plugin after the installation process.

To define the actions to use on a particular type of package (bin, src or doc) you must define a property on the web-dist target of the plugin's ant build file. The properties are:

- madkit.plugin.actions.bin: for the binary package
- madkit.plugin.actions.src: for the source package
- madkit.plugin.actions.doc: for the documentation package

For the moment only one action is available, docref.

### DocRef Action

The DocRef action lets you add references to html documents. These references will be mainly used by the DocBrowers plugin.

The DocBrowser divides the references into sections, the main ones are:

- api: used when adding a link to an agent or MAS api
- manual: when adding a Manual
- demo:when adding a demo
- tech: when adding specifications or technical reports for Madkit

The attributes of this action are:

- name: defines the name to display in the madkit documentation index
- url: defines the url of the file. This url can be absolute (e.g. http://java.sun.com) or relative to the madkit installation directory
- section: defines the section of document
- absolute: defines if the url is absolute or relative to the madkit directory. This is an optional attribute, and by default is false.

Important: You don't need to add a docref action for the plugin API, this is automatically done by the ant generic file.

Here is an example taken from the communicator's build file.

    <property name="madkit.plugin.actions.doc"

    value='<action id="docref" url="plugins/communicator/docs/communicator.html" name="Communicator Manual" section="manual"/>'/>

## Troubleshooting

### The Plugin manager crashes with a ZipException while updating the plugins list

While the plugins are checked with a md5sum, the plugins.zip file is not. So the plugin manager will try to open the downloaded file as a zip. However, the server might not allways send the zip. To verify if the plugins.zip is really being downloaded, try wget http://download.url/download.php?file=plugins.zip and check if the downloaded file is really a zip file. Normally you will find instead a html page, just look for the real url and use it as you Server Download url.