Table of Contents

Before Development

  1. Ensure that Git and Java JDK >= 11 are installed.
    You can get a OpenJDK distribution from e.g. Adoptium.
    Note: While Java 11 is required for building, running PMD only requires Java 8.
  2. Fork the PMD repository on GitHub as explained in Fork a repository.
  3. Clone your forked repository to your computer: 
    git clone git@github.com:your_user_name/pmd.git --depth=10 --no-tags
  4. Clone additionally the build-tools repository. It contains some settings, we’ll later use for configuring IDE: 
    git clone git@github.com:pmd/build-tools.git

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

    cd pmd
./mvnw clean verify -DskipTests

    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.

Reproducible Builds

Since PMD 6.24.0, we are creating Reproducible Builds. As we use Maven for building, the following limitations apply:

  • Generally give different results on Windows and Unix because of different newlines. (carriage return linefeed on Windows, linefeed on Unixes).

    We build our releases under Linux on Github Actions.

  • Generally depend on the major version of the JDK used to compile. (Even with source/target defined, each major JDK version changes the generated bytecode.).

    We build our releases using OpenJDK 11.

You can check the reproducible build status here: https://github.com/jvm-repo-rebuild/reproducible-central/blob/master/content/net/sourceforge/pmd/README.md

How to build the documentation?

cd docs
bundle install # once
bundle exec jekyll build

You’ll find the built site in the directory _site/.

For more info, see README in docs directory.

How to test SNAPSHOT builds?

Every push to our main branch creates a new SNAPSHOT build. You can download the binary distribution from https://sourceforge.net/projects/pmd/files/pmd/. The binary distribution ZIP file behaves exactly the same as the real release: Just unzip it and execute PMD.

If you integrate PMD as a dependency in your own project, you can also reference the latest SNAPSHOT version. However, you also need to configure an additional Maven Repository, as the SNAPSHOTS are not published in Maven Central.

Use the OSSRH snapshot repository url: https://oss.sonatype.org/content/repositories/snapshots. For Maven projects, this can be configured like:

<repositories>
 <repository>
   <id>sonatype-nexus-snapshots</id>
   <name>Sonatype Nexus Snapshots</name>
   <url>https://oss.sonatype.org/content/repositories/snapshots</url>
   <releases><enabled>false</enabled></releases>
   <snapshots><enabled>true</enabled></snapshots>
 </repository>
</repositories>

Have a look at https://oss.sonatype.org/content/repositories/snapshots/net/sourceforge/pmd/pmd/ to see which SNAPSHOT versions are available. Note that old SNAPSHOT versions might be removed without prior notice.

General Development Tips

  • Use a IDE, see one of the other guides
  • Contributing via GitHub and Pull Requests
  • Keep your fork up-to-date
    • You can do this either via GitHub’s Web UI
    • Or manually: 
      git remote add upstream git@github.com:pmd/pmd.git
git checkout main
git pull --ff-only upstream main
git push origin
    • See also Newcomers’ Guide
  • Always create a dev branch when you are going to commit something, so that you can easily create a PR later on.
  • Build a single module only: Always (re)building the complete PMD source takes quite a while. If you only change one module, you build and test just this single module to speed up development. Eg. if you changed a rule in pmd-apex only, you can just build this: 
    ./mvnw verify -pl pmd-apex

    Caveats: We have some integration tests, that run only after all modules have been built. You could break these without noticing.
    Note: In our CI (via GitHub Actions) we always build the complete project.

Tags: devdocs