# Building PMD with Eclipse

Table of Contents

## Import PMD Project

1. Download the latest Eclipse IDE for Enterprise Java and Web 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`.

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

While PMD still runs with Java 8, we need at least Java 11 for building and running unit tests. To make sure, Eclipse uses Java 11 instead of Java 8, go to Window > Preferences and select Java > Installed JREs. Make sure, you have a Java 11 or newer available. Then go to “Execution Environments”, choose “JavaSE-1.8” and check your Java 11 installation on the right.

## Running unit tests

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

If you do this for other projects, you might get some build errors. Try to ignore them for now - at least some unit test should be executed. See also “Known Issues” below.

## Running / Debugging PMD

- Navigate to class `PmdCli`
- Right-Click and select “Run As -> Java Application”.
- Ignore any build errors for now and choose “Proceed”.
- In the console you should see the output from PMD.
- Now you have a run configuration: Modify this through menu “Run > Run Configurations…”
  - In tab arguments: use `check --help` as program arguments
  - In tab dependencies you can add the modules of languages you want to test with to the classpath, eg. pmd-java
- Instead of run, you can use the same configuration for debugging.

## 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 `https://checkstyle.org/eclipse-cs-update-site` 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 `https://m2e-code-quality.github.io/m2e-code-quality-p2-site/`
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, unselect the option “Clean 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

## Running the designer

The designer lives in a separate repository, that you’ll need to fork and clone first: Designer repository

    git clone git@github.com:your_user_name/pmd-designer.git

See Contributing Guide of the Designer for details.

- 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

- Eclipse is very slow without making progress when building the complete PMD project.
  - It could be, that eclipse runs out of memory. Open `eclipse.ini` and replace `-Xmx2048m` with `-Xmx4096m`. Restart eclipse.
  - Close the other languages modules, that you are not interested in. The fewer projects that are open the better for eclipse performance.
  - Temporarily disable “Project > Build Automatically” and build the project using Maven: Run `./mvnw compile` and after that select the top level project in Project Explorer (“pmd”) and use “File > Refresh”. Then enable “Build Automatically” again.

- There is no good Kotlin support for Eclipse. Many tests depend on Kotlin and at least pmd-apex uses Kotlin for the main sources. This means, you need to compile the project with Maven without Eclipse.

  As long as you don’t need to change the Kotlin code, you can ignore this for now. In order to be able to execute the tests, there is a 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 “pmd-scala_2.13” 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”.

Tags: devdocs