How to use custom rule sets with the plug-in

Using custom rule sets with the plug-in is quite simple. PMD searches the rule sets files on the classpath defined for the plug-in. So, to use custom rule sets, they must be on the PMD Plug-in classpath.

The way to do that with Eclipse is to package the rule sets in a plug-in fragment. A fragment is an extension of a plug-in and all the classes and ressource files it contains are automatically added to the main plug-in classpath.

The steps to add a custom rule set are :

  1. Create a plugin fragment as an extension to the PMD Plug-in
  2. Optionnaly, develop your rule class implementation
  3. Create one or more rule set files
  4. Test the fragment
  5. Package the fragment
  6. Install the fragment in the target Eclipse environment

The following details these steps.


1. Create a plugin fragment as an extension to the PMD Plug-in

The first step is to setup the plug-in development environment. Open the Preferences dialog box. Select Target platform in the Plug-in devlopment category. Then push the Select All button and click OK to close the window.

The second step is to create a plug-in project for the fragment.

  • Choose the File->New->Project... menu
  • Select the Plug-in development Category and the Fragment project item ; click Next
  • Give a name to the project ; a plug-in project name is normally formed like a package name, for example : com.foo.pmd.rules
  • Specify the fragment id ; by default the project name is used. Select also the project type. A Java project is required. Specify the name of the jar files and modify the default classes and sources directories if needed.
  • Choose a blank fragment project and click Finish.
  • Ignore the Problem occurred window and click OK.

The last step is to configure the plug-in manifest.

  • In the project folder, edit the fragment.xml file.
  • In the plug-in id field, type
    net.sourceforge.pmd.eclipse
    In the Plug-in version field type the PMD plug-in version (ex. 1.0.0). In the Match Rule field, select how you want to be bound with the PMD Plug-in. A good choice is
    Greater or equal
    so that if the PMD Plug-in is upgraded, the fragment will still be activated.
    
    			
  • Save the changes and close the editor.

The more complex task is done ;-)


2. Optionnaly, develop your rule class implementation

Check the PMD official documentation to learn how to develop rule classes.


3. Create one or more rule set files

This step is simply to create one or more XML rule set files. Place them in the source directory. Read the PMD documentation to learn how to write rule set files.


4. Test the fragment

Before deploying the fragment, it is necessary to test it. To do that, the simplest way is to launch a test Eclipse environment :

In the Run menu, select Run as->Run-time workbench. This will launch a secondary workbench with all the installed plug-ins and the fragment currently in development. In that workbench, create a test Java project to test the rule set. (see step 6 to learn how to configure the PMD Plug-in).


5. Package the fragment

Before deploying the fragment, it is necessary to package it. Export the project with the export wizard and select Deployable plug-ins and fragments. Select the fragment project and specify the zip file that will form the distribution package.


6. Install the fragment in the target Eclipse environment

Unzip the distribution package on the target environment. If the target environment is Eclipse, then the Eclipse install directory must be "eclipse" ; unzip the distribution file from the parent directory (the directory in the distribution file begins with "eclipse/plugins...").

If the target environment is WSAD, unzip the distribution file from the installation path of WSAD.

To activate the custom rule set, open the preferences window and select the Ruleset selection tab in the PMD category. Type the path and name of the custom rule set file in the combo box and press the Add rule set button. The custom rule set is added to the list. Press OK to close the Preferences dialog.

Now, the custom rule set file will be used each time a PMD check will occur.