Note: FlexPMD plugin requires FlexPMD v.1.0.1 Make sure you download the latest version

FlexPMD eclipse plugin

FlexPMD eclipse plugin is a beta release that targets two different type of users with two different goals:

  1. Code review workflow: As a code reviewer I want to be able to audit and review the quality of an entire project or any given functional area in terms of PMD violations.
  2. Development workflow: As a developer I want to see PMD violations in the files I'm working in. If a file changes the violations should be updated immediately.

If you find any problem or want to submit any feature request feel free to log it in in the bugbase http://bugs.adobe.com/jira
If you have any question use the forums http://forums.adobe.com/community/opensource/flexpmd/

1. Installation

At the moment the plugin has been tested in the following environments:

  • FlashBuilder 4 Beta 2 standalone
  • FlashBuilder 4 + Eclipse 3.5
  • FlashBuilder 4 + Eclipse 3.4
  • FlashBuilder 3 + Eclipse 3.4

The plugin has to be installed following the standard Eclipse update mechanism. Open eclipse and follow these steps:

  1. Help > Install new software
  2. Use the following update site: http://opensource.adobe.com/svn/opensource/flexpmd/plugin/trunk/flex-pmd-eclipse-plugin-site
  3. Select FlexPMD feature and proceed with the installation

2. Configure FlexPMD plugin

Before using the plugin you will have to configure FlexPMD on eclipse preferences so that FlexPMD and FlexCPD jars, among other things, are properly referenced.

  • Download FlexPMD command line tools from here
  • FlexPMD command line. This is a mandatory field. You have to select the flex-pmd-command-line.jar you want from your hard drive.
  • FlexPMD custom ruleset. You can leave this field empty, if so a default ruleset will be used.
  • FlexCPD command line. You have to select the flex-pmd-cpd-command-line.jar you wish from your hard drive.

3. Supported workflows

3.1 Code review workflow

Once FlexPMD is properly configured you'll be able to run FlexPMD on any folder and see the violations in the FlexPMD View.

  1. Select any source folder in a project
  2. Right click on it
  3. Select FlexPMD > Run FlexPMD

At this point the FlexPMD View will appear displaying the results grouped by violation.

In this view you will be able to double click the files containing the violations, they will be opened in the apropiate FlashBuilder editor.

If you prefer you can group the violations based on the class they apply to. In this case double clicking the child nodes will open the file and navigate to the affected line, double clicking on the class node will open the file.

Group by Class is an interesting filter if you're looking at how certain areas of your code are affected. Group by Violation filter is handy when you want to know how the violation's distribution looks like.

All violations will be added as markers to the source classes as errors, warnings or info messages. After looking at the report you can always get rid of the markers by right clicking on a project and select FlexPMD > Clean FlexPMD markers. Additionally you can remove a concrete error by right-clicking on it and selecting delete.

3.2 Development workflow

If you're interested in a more interactive and integrated development workflow you can add to your project a FlexPMDNature.

  1. Right click in a project
  2. Select FlexPMD > Add FlexPMDNature

Note: If at any point you want to remove the nature you can selecte FlexPMD > Remove FlexPMD Nature

After building your project (fully or incrementally) FlexPMD will be executed and violations will be listed in the standard problems view

Double clicking the errors, warnings or info markers will open the file in FlashBuilder editors. You'll see the markers inline in the files as well:

4. FlexPMD Outline

In the FlexPMD Outline View you'll see the violations in the currently opened editor.

If the arrows button is toggled, whenever the file is saved FlexPMD will be re-executed on it and the Outline will be updated providing always up-to-date information to the developer with very little delay and without having to compile the entire project.

Double clicking on any violation will navigate to it in the editor.

It's important to note that the OutlineView works on any project, not only the ones with a FlexPMDNature. If you open a .as or .mxml file in a project that doesn't have flexPmdNature and the OutlinView has the monitorize option toggled, after the first save the outline will be updated.

5. FlexCPD integration

You can execute FlexCPD by right-click in a source folder and select FlexPMD > Find suspect cut & paste. The FlexCPD view will be automatically opened displaying the results.

6. Usage strategies

It's very likely that when you start using FlexPMD on your projects you'll get lots of violations. This can by several reasons. Below you'll find some tricks you can use in order to make FlexPMD more useful by avoiding unnecessary noise.

6.1 Fine tune your ruleset

If you define a violation in your ruleset as an error the plugin will re-inforce the rule by breaking your build. Whenever you try to run your project you'll get a message telling you there're errors in the project and prompting you if you want to continue.

Even though you will be able to continue the execution it's not a good practice. If you operate this way, in could be the case that, compilation errors would be swallowed by FlexPMD errors. Make sure you have a good flexPMD error strategy defined in your ruleset and make sure your team follows it. If accordingly to your strategy there's a FlexPMD error you have to fix it before continuing.

6.2 Filtering problems

Once you add the FlexPMD nature or execute FlexPMD on any folder the violations will be reported as standard markers and errors in the standard Eclipse errors view. This means that if your ruleset defines a certain violation as an error your project will have an error and will complain when trying to run it.

As displayed in the image below, FlexPMD errors, warnings and info messages are displayed all together with Flex compiler errors. This, in lots of cases, can distract developers and swallow important compiler notifications. Although not specific to the FlexPMD plugin, there's an easy way to create a specialised view for only displaying FlexPMD issues. To do so, use the following steps:

  1. Open the problems view
  2. Create a "new problems view"

  1. In the dialog assign it the "FlexPMD Problems" name
  2. In the new created view select "Configure contents..."

In the configuration dialog select

  • Severity: Error, Warning, Info
  • Types. Unselect all except "FlexPMD error" type

Then in the standard "Problems View" follow the same process to filter out "FlexPMD errors". Uncheck its type from the types list.

6.3 Projects with lots of violations

Most probably, even though you have customised and fine tuned your ruleset, you'll get error violations in your projects that will distract you while developing. In most cases it might not be an option to invest time on fixing these violations thus reducing the FlexPMD added value.

Here's what the plugin can do for you in these cases.

Don't add flexPMDNature to your project. This will prevent flexPMD from scanning and reporting violations on the entire project.

  1. Open the outlineView and toggle on the "Monitorize" icon.
  2. Start coding
  3. FlexPMD will only report violations on files you modify. The oultine view will be populated and updated only after your first save. Basically a developer that modifies an existing file will be the responsible to fix the violations on this file contributing to a clean-code practice.

7. Upcoming features in future releases

  1. Ability to configure FlexPMD at the project level, not at the workspace level, so that each project can use a different ruleset (sharable across the team by any SCM system).
  2. Improve installation experience. At the moment FlexPMD command line tools are downloaded and installed separately. While we want to be able to update the command line tools without updating the plugin we could improve the experience. i.e: A button in the preference page that would automatically download the tools and automatically configure the settings.
  3. Better integration with FB to detect source folders in the classpath.
  4. Quick fixes.

8. Known issues

  1. If you have "build automatically" checked in your project and you select "monitorize" in the FlexPMD outline view, FlexPMD will be executed several times.
  2. If you find any problem feel free to log it in in the bugbase http://bugs.adobe.com/jira
  3. If when you run FlexPMD you get empty results or apparently it doesn't even execute these might be the casues:

9. Where can I get the logs

If you have any problem you can ask for help in the forums. For a quicker resolution please make sure you've read the Known issues section above and that you provide the following information:

  1. Flash Builder version
  2. Are you using standalone version or as a plugin?
  3. If using the plug-in version which version of Eclipse are you running?
  4. Provide the relevant parts of eclipse logs. Eclipse logs are in the .metadata folder of your workspace. .metadata folder is normally hidden. In this folder you will find the file .log. Additionally, if there's nothing relevant in this file, you can launch eclipse from the command-line with the -debug option. This will output more helpful and detailed information of what might be going on behind the scenes.