Plugin development getting started

PowerTAC Plugin Development - Getting Started

Prerequisites, Recommended Setup, Reading Material

Please refer to the getting started wiki page.

Note: If you're contributing, please read and follow our Development Policies completely.

Building, Testing, and Deploying a PowerTAC Plugin

The PowerTAC server is made up of separate modules. In the next few sections we walk you through the creation, testing and Deployment of a new PowerTAC module, in this case a module that simulates the physical environment within a PowerTAC competition.

Step1: Create a new, empty grails plugin

  cd /plugin/home/folder
  grails create-plugin powertac-physical-environment
  cd powertac-physical-environment

Step2: Define basic plugin description and dependencies

In the file PowertacPhysicalEnvironmentGrailsPlugin.groovy add your name, the plugin title and a short description.

Add a plugin dependency for the powertac-common plugin (as of writing of this guide, the latest version of the powertac-common plugin was 0.2.3 0.9). Note: You have to use CamelCase Notation for the plugin name (i.e. powertacCommon instead of powertac-common otherwise automatic plugin resolution fails). The powertac-common module defines the common database layout as well as helper methods and all plugin interface definitions.

def dependsOn = ['powertacCommon': '0.9 > *']

Note: The above notation says to use powertacCommon 0.9 or later. Once development has stabilized, or if you want to temporarily stick with a particular version, it may make sense to define the dependency as 0.9 which means "only version 0.9."

The resulting file should look like this:

Step 3: Add .gitignore file to your plugin project

Add a .gitignore file to the root folder of your project in order to ignore class files etc. IDE project files should be committed to make it easy to open your plugin in an IDE.

Step 4: Adjust the plugin build configuration

Open the file grails-app\conf\BuildConfig.groovy

If you want to depend on local versions of other plugins, rather than a version that was packaged and distributed from the central repository, add lines like

grails.plugin.location.PowertacCommon = "../powertac-common"

grails.plugin.location.PowertacServerInterface = "../powertac-server-interface"

near the top of BuildConfig.groovy, above the clause grails.project.dependency.resolution.

Add the PowerTAC central plugin repositories to the dependency resolution section of the file:

mavenRepo "http://ibwstinger.iw.uni-karlsruhe.de/artifactory/plugins-release-local/"

mavenRepo "http://ibwstinger.iw.uni-karlsruhe.de/artifactory/libs-release-local/"

The result should look like something like this (old screenshot) (note: ask the PowerTAC admins for login credentials if you want to use remote deploy feature):

Step 5: Locally install plugins and check configuration

If you want to download your plugin dependencies rather than depending on plugins in your development environment, then you need to install powertac-common and powertac-server-interface plugins:

grails install-plugin powertac-common

Optionally install maven-publisher plugin if you want to automatically deploy the plugin into the PowerTAC plugin repository via command line (otherwise you can also do that manually via the plugin repository's web interface at http://ibwstinger.iw.uni-karlsruhe.de/artifactory)

grails install-plugin maven-publisher

Now type grails run-app in the command line to start a tomcat application server locally. Note: The first start-up will take a bit longer as the powertac-common plugin and optionally the maven-publisher plugin have to be downloaded from the remote repostitories and locally installed on your computer.

##Step 6: Develop your own business logic At this point you're done with setting up the plugin and you can start developing your business logic. In this case we create a simple physical environment model.

Create a new service class (the default location where business logic is stored in grails) by typing in the command line:

grails create-service org.powertac.physicalenvironmentmodel.PhysicalEnvironment

Open the new created file at

grails-app/services/org/powertac/physicalenvironmentmodel/PhysicalEnvironmentService.groovy

Make this class implement the interface org.powertac.common.interfaces.PhysicalEnvironment which is provided by the powertac-common plugin and create method stubs for all methods defined in the interface (your favorite IDE will probably do that automatically for you).

The result should look like this (old screenshot):

Now it's time to write the plugin's business logic. Before you start your implementation, please make sure that you understand and adhere to the few PowerTAC conventions, particularly the [[table ownership and package naming|Role-concept]] conventions. Also make sure that you understand and follow the PowerTAC Development Policies.

##Step 7: Test your code At PowerTAC we favor test driven development or at least production code that is well covered with unit and integration tests. Grails actually supports you in writing unit and integration tests with a very nice mock framework for unit testing and a dedicated test database for integration testing.

When you created the PhysicalEnvironmentService.groovy, grails also created a corresponding PhysicalEnvironmentServiceTests.groovy class located under test/unit/org/powertac/physicalenvironmentModel. Use this test class to check that you business logic is not flawed. Not particularly, that method calls might come with null values in the parameter list. Account for that!

Once you've written your test code and the corresponding business logic that satisfies all tests, you can execute it on the command line with grails test-app (user grails test-app -unit for executing unit tests and grails test-app -integration for executing integration tests only).

You can also install cobertura code-coverage plugin in order to get a better idea on how well your test code is covering your business logic:

  cd /plugin/home/folder
  grails install-plugin code-coverage                   
  grails test-app -coverage

All test results are stored under target/test-reports

##Step 8: Deploy the plugin Once you've finished writing your plugin it needs to be packaged and made accessible to others. To compile and package the plugin, just execute

grails package-plugin

This will produce a zip file in your plugin root folder, which contains all relevant plugin data and excludes all local configuration (such your local test database definitions etc.) by default. For more details on which files are included or excluded please refer to the grails plugin development guide. You can then send this zip file to one of the PowerTAC admins or manually upload it to the plugin repository using its webinterface.

If you want to automatically deploy the plugin to the PowerTAC plugin repository, make sure that you have installed the grails maven publisher plugin. In the command line...

  grails list-plugins
  grails grails install-plugin maven-publisher

Next, make sure that you have added your publishing configuration to grails-app/conf/BuildConfig.groovy. Below the last line of the original config add:

  grails.project.dependency.distribution = {
    remoteRepository(id: "powertacPlugins", url: "http://ibwstinger.iw.uni-karlsruhe.de/artifactory/plugins-release-local/") {
      authentication username: "[your powertac plugin repo username]", password: "[your password]"
    }
  }

Please request login credentials for the plugin repository on the Power TAC Developers List. John, David, or Carsten will help you out. Put these into the BuildConfig.groovy file as shown above and then run the following command on the command line:

grails maven-deploy --repository=powertacPlugins

This will package your plugin and then automatically deployed it into the PowerTAC plugin repository (Note: for the first run, the plugin downloads a lot of additional dependencies. That takes some time. The next run will be much faster). After the deploy process has finished, please check, that your plugin is correctly published.