Setup IDE - pmd/pmd GitHub Wiki

This guide explains, how to import the source code of PMD into your favorite IDE and start hacking on PMD.

This guide does not explain, how to use a PMD plugin in your favorite IDE, for this see, please see Plugins and Tools / Integrations.

Note: this is WIP - once this documentation is matured, it will be moved to the official documentation.

Table of Contents

  1. Preparation
  2. Eclipse
  3. IntelliJ Idea

Preparation

  1. The first step is, to clone the repository to get the code. Fork the repository https://github.com/pmd/pmd on github and clone your personal fork. Assuming your github user name is "johndoe", the command is:

    $ git clone https://github.com/johndoe/pmd.git --depth=10 --no-tags

    See the Newcomers'-Guide for detailed instructions.

    This first step is needed regardless which IDE you are going to use.

    Note: You can also clone the repository from within your IDE, but this is not described here in this guide.

  2. Clone additionally the build-tools repository. It contains some settings, we'll later use for configuring IDE:

    $ git clone https://github.com/pmd/build-tools.git

  3. Make sure, you have Java Platform (JDK) 11 installed. Note: You have to use java11 or later in order to build PMD - older java versions are not supported.

  4. To make sure your Maven environment is correctly setup, we'll build pmd once:

    $ cd pmd
$ ./mvnw clean verify

    This will help with Maven IDE integration. It may take some time, because it will download all dependencies, so go brew some coffee to get ready for the steps to come.

Eclipse

  1. Download the latest Eclipse IDE for Java Developers
  2. Install it by extracting it into a directory of your choice
  3. Start eclipse. You'll be asked for a workspace. It's recommended to use an extra, separate new workspace for PMD, because you'll import many projects. Otherwise you might clutter your existing workspace with PMD projects.
  4. Close the welcome screen, if it is shown.
  5. Select menu File, Import.... In the dialog, select Maven / Existing Maven Projects and click Next.
  6. As Root Directory select the directory, into which PMD's repository has been cloned.
  7. Then click Select All and then Finish.

You might be asked about a missing m2e connectors for the kotlin plugin. You can simply select Resolve All Later and ignore this problem for now.

Now all PMD projects are imported. This might take a while. All the projects will appear on the left inside the Project Explorer.

Running unit tests

To verify, that the basics work, right-click on the pmd-java project and select Run As -> JUnit Test. If everything is well, the project will be built and the unit tests are executed.

You probably get some build errors in some projects. Try to ignore them for now - at least some unit test should be executed. See also "Known Issues" below.

Code Templates, Formatter

  1. Menu Window -> Preferences
  2. Under Java / Code Style / Code Templates: Click Import... and choose the file eclipse/pmd-eclipse-codetemplates.xml from the "build-tools" repository.
  3. Under Java / Code Style / Formatter: Click Import... and choose the file eclipse/pmd-eclipse-code-formatter.xml from the "build-tools" repository.
  4. Under Java / Code Style / Clean Up: Click Import... and choose the file eclipse/pmd-eclipse-code-cleanup.xml from the "build-tools" repository.
  5. Under Java / Code STyle / Organize Imports: Click Import... and choose the file eclipse/pmd-eclipse-imports.importorder from the build-tools" repository.
  6. Click Apply and Close

Checkstyle

We are going to install two plugins: The checkstyle plugin itself and the m2e-code-quality plugin, which seamlessly activates and configures checkstyle in eclipse according to the maven configuration of PMD.

  1. Menu Help, Install New Software...
  2. Enter the URL http://eclipse-cs.sourceforge.net/update/ into the text field and press enter.
  3. Select the checkbox for "Checkstyle" and click Next
  4. Restart eclipse if you are requested to do so.
  5. Install the next plugin for the URL http://m2e-code-quality.github.com/m2e-code-quality/site/latest
  6. This time, select only "Checkstyle configuration plugin for M2Eclipse" and click Next
  7. Restart eclipse if you are requested to do so.
  8. Finally, right click on one project in the package explorer. Select Maven / Update project... in the context menu. In the dialog, select all projects and click OK.

Other settings

  • Consider displaying the white space characters: Window, Preferences; General / Editors / Text Editors: Show whitespace characters
  • Insert spaces for tabs also in text files: Window, Preferences; General / Editors / Text Editors: Insert spaces for tabs

Executing the Designer

The designer lives now in a separate repository, that you'll need to clone first:

$ git clone https://github.com/pmd/pmd-designer.git

Import the designer project via menu File, Import.... In the dialog, select Maven / Existing Maven Projects and click Next.

Open the class net.sourceforge.pmd.util.fxdesigner.DesignerStarter via menu "Navigate / Open Type...".

Right click in the editor window and select "Run as -> Java Application".

Known Issues

  • pmd-apex, pmd-dist, pmd-doc and other projects are missing the project "pmd-apex-jorje". The project is actually existing, but it is not a java project in eclipse.

    Workaround:

    1. Build the project once from outside eclipse: $ ./mvnw clean install -f pmd-apex-jorje/pom.xml This installs the dependency in your local maven repository.
    2. In eclipse, close the project "pmd-apex-jorje". That way, eclipse will use the jar file from the local maven repository instead of the project.

  • Many tests depend on kotlin. Kotlin is not really supported in Eclipse. As long as you don't need to change the kotlin tests, you can ignore this for now. In order to be able to execute the tests, there is a similar workaround:

    1. Build the project "pmd-lang-test" once from outside eclipse: $ ./mvnw clean install -f pmd-lang-test/pom.xml This installs this module in your local maven repository.
    2. In eclipse, close the project "pmd-lang-test". That way, eclipse will use the jar file (which contains the already compiled kotlin base test classes) from the local maven repository instead.

  • pmd-scala project has no source code / tests: If you don't want to work on scala, then you can simply close all scala projects.

    For scala, there are two versions: 2.12 and 2.13. Both share the same code, which is in pmd-scala-modules/pmd-scala-common. However, this code is not used directly, but referenced from the two projects pmd-scala-moduls/pmd-scala_2.12 and pmd-scala-moduls/pmd-scala_2.13. When working on scala, it is recommended to close pmd-scala_2.12 and only work on pmd-scala_2.13. Then you need to configure "pmd-scala_2.13" manually, so that eclipse finds the source folders:

    1. Right-click on the project and open the "Properties". On the left navigate to "Java Build Path".
    2. Open the tab "Source"
    3. Delete the all source folders
    4. Click on "Link Source..." and manually choose via "Linked folder location" the path in the repository to pmd-scala-modules/pmd-scala-common/src/main/java. Name it "src-main-java" and click "Finish".
    5. Repeat it for pmd-scala-modules/pmd-scala-common/src/main/resources. Name it "src-main-resources".
    6. Repeat it for pmd-scala-modules/pmd-scala-common/src/test/java and pmd-scala-modules/pmd-scala-common/src/test/resources.
    7. Change "src-test-java" to "Contains test sources: Yes", select "Source Output Folder > Specific Output Folder" and choose "target/test-classes".
    8. Repeat this for "src-test-resources".

IntelliJ IDEA

  1. Download the community edition of IntelliJ IDEA from jetbrains.
  2. Install it, that means, extract the archive
  3. Start it with bin/idea.sh
  4. In the startup dialog, choose the button Open and select the folder, into which PMD's repository has been cloned. Then select "Trust Project". After that, IJ will automatically detect that PMD is a maven project and import it. Make sure, you have previously built PMD on command line via ./mvnw clean verify, as described in the preparation step.
  5. If you are using IJ for the first time, you'll need to configure the path to your installed Java SDK. You have to use at least Java 9 here. If the dialog doesn't show automatically, you can open it with menu File > Project Structure (CTRL+ALT+SHIFT+S). On the left, choose "Platform Settings > SDK" and add your Java SDK. Then choose "Project Settings > Project" and select the SDK for PMD.
  6. Finish the wizard and wait a bit, until all PMD modules appear on the left.

Running Unit Tests

  • Right click on "pmd-java" and select "Run 'All Tests'"
  • You can run individual unit tests or a single unit test class by right-clicking, or CTRL + SHIFT + F10. You can debug the current Run configuration using SHIFT + F9.

Setting up Checkstyle

If you don't have the Checkstyle plugin:

  • Open File > Settings (CTRL+ALT+S) and navigate to "Plugins" on the left
  • Click on "Browse repositories" on the bottom
  • Search for "Checkstyle-IDEA" and click "Install"
  • When done, restart IJ

Once you have the Checkstyle plugin:

  • Open File > Settings (CTRL+ALT+S) and navigate to "Tools > Checkstyle" on the left
  • Make sure to select the latest Checkstyle version and click Apply
  • Add a configuration file with the Add button on the right
  • Choose a descriptive name, then tick "Use a Checkstyle file accessible via HTTP" and enter the following URL: 
    https://raw.githubusercontent.com/pmd/build-tools/master/src/main/resources/net/sourceforge/pmd/pmd-checkstyle-config.xml
  • Tick the "Active" checkbox for this added checkstyle configuration

Formatter and inspection configuration

Import the code style settings (formatter) so that it conforms with our Checkstyle config. To do that, go to File > Settings (CTLR+ALT+S) then navigate to "Editor > Code Style > Java". Click on the cogwheel symbol, choose "Import Scheme > IntelliJ IDEA code style XML" and choose the file intellij-idea/PMD-code-style.xml from the build-tools repository.

Take some time to tweak the inspections so that they conform to the code style, for example flagging switch statements with no default case. This takes some time but can make your code much cleaner. To do that, go to File > Settings then navigate to "Inspections > Java".

Running the designer

The designer lives now in a separate repository, that you'll need to clone first:

$ git clone https://github.com/pmd/pmd-designer.git

See Contributing Guide of the Designer for details.

  • We recommend creating and saving a new run configuration (see IJ doc), using the "Application" template. On IJ < 2017.3, there is also a "JavaFX Application" template.
  • When editing the run configuration, add -v to the program arguments, to get debug output
  • Be sure to use the classpath of the pmd-ui module

Known Issues

  • Some compilation errors: If you didn't build PMD from command line outside of IDEA, then the sources, that are usually generated during the build, are not available. You can right-click on the PMD project and select "Maven > Generate Sources and Update Folders". It seems, that IDEA doesn't use the correct JDK when executing this command. Try again - it seems, it works on the second try only. After that, the folder are there, but IDEA doesn't use them. Select "Maven > Reimport".
  • When editing FXML or CSS files for the designer, IJ sometimes fails to put the updated version in the classpath when running. You need to run mvn process-resources -pl pmd-ui.
  • As a quickfix for the two problems above, mvn compile is quick to execute when your Maven dependency cache is up-to-date.