--- schema_version: "1" id: 2a1060274cf3b5cc663817e298843bc0ca74df88b88ebcd2c5f876a93e002cbf title: PMD Customization (Retired) collection: developer version: current locale: en-us portal_url: https://docs.salesforce.com/developer/current/en-us/code-analyzer/salesforce-code-analyzer/guides/v3x/custom-configuration/pmd-config.md canonical_url: https://developer.salesforce.com/docs/platform/salesforce-code-analyzer/guide/pmd-config.html source_site: developer.salesforce.com content_type: documentation content_hash: 86f804723ea73f526fe2a744529cb3bba863864a8114c9b07a04a77b83119b1e products: - Salesforce Code Analyzer --- # PMD Customization (Retired) By default, Salesforce Code Analyzer's catalog of PMD rules includes the PMD built-in rules and any custom rules that you added with `scanner rule add`. Filter which rules are run using flags such as `--category`. ## Customize the Default PMD Catalog To replace the catalog with your own custom catalog, use `--pmdconfig`. With this flag, you can: - Indicate a specific set of rules to run without using filtering flags such as `--category` - Modify the properties of existing rules to meet your needs - Define and run new XPath-based rules without permanently adding them to the catalog Create your custom rules file just like another other PMD category or [ruleset file](https://docs.pmd-code.org/latest/pmd_userdocs_making_rulesets.html#creating-a-ruleset). Keep these limitations in mind. - The PMD built-in rules can be referenced freely with the `ref` property. - Custom rules defined in other files can be referenced through the `ref` property only if they’re bundled into a JAR as described in Authoring Custom PMD Rules and registered via `scanner rule add` as described in Managing Custom PMD Rules. This constraint applies to XPath-based and Java-based rules. - Custom XPath-based rules can be declared inline. **note:** Because `--pmdconfig` replaces our catalog with yours, rule-filter flags such as `--category` and `--ruleset` aren’t applied to PMD rules, though they’re still applied to other engines. Only the PMD rules that you specify in your config file are evaluated. ### Invoke Your Custom PMD Catalog To invoke your rules in Code Analyzer, run `scanner run --pmdconfig filename`, and pass the path to your rule reference file: `$ sf scanner run —target /path/to/your/target —pmdconfig /path/to/rule_reference.xml` #### Replace these values: - `/path/to/your/target`: The source code location. - `/path/to/rule_reference.xml`: The location of the PMD rule reference file. You can specify the rules that you invoke on PMD using `--pmdconfig`. Using `–pmdconfig` causes other filter parameters to be ignored, such as `–category` and `–ruleset`. `$ sf scanner run --engine eslint-typescript,pmd --pmdconfig /path/to/ruleref.xml --target /path/to/target` #### Replace these values: - `eslint-typescript,pmd`: The location of ESlintrc config. - `/path/to/ruleref.xml`: The location of the PMD rule reference file. - `/path/to/target`: The source code location. ## Authoring Custom PMD Rules To be compatible with Code Analyzer, build your PMD custom rules following these guidelines: - Declare your new XPath or Java-based rules in custom category XML files using this format: `/category//.xml`. For more info, read the PMD [XML rule definition](https://docs.pmd-code.org/latest/pmd_userdocs_extending_writing_rules_intro.html#xml-rule-definition) documentation. - Combine your custom rules and the PMD built-in rules into custom rulesets in XML files using this format: `/rulesets//.xml`. For more info, read [Making rulesets](https://docs.pmd-code.org/latest/pmd_userdocs_making_rulesets.html) in the PMD documentation. - Register custom rulesets or [XPath-only](https://docs.pmd-code.org/latest/pmd_userdocs_extending_writing_xpath_rules.html) custom categories with Code Analyzer as standalone XML files. - Compile your Java-based rules, and bundle them into a JAR along with your rule declaration files, then register that JAR with Code Analyzer. We recommend using a build tool such as [Maven](https://maven.apache.org/plugins/maven-jar-plugin/) or [Gradle](https://docs.gradle.org/current/dsl/org.gradle.api.tasks.bundling.Jar.html) to manage the dependency on PMD and automate the process of building the JAR. Use our [example repo](https://github.com/forcedotcom/sfdx-scanner/tree/dev/sample-code/pmd-example-rules) as a scaffold to build your own project. ## Managing Custom PMD Rules Use the `scanner rule add` [command](https://developer.salesforce.com/docs/platform/salesforce-code-analyzer/command-reference/add.md) to add a custom rule to the Code Analyzer catalog. Rules added in this way can then be invoked with `scanner run` the same way that PMD default rules are invoked. Use the `-p|--path` parameter to specify the XML file containing your XPath-based rules or the JAR containing your Java-based rules. You can specify multiple files to add multiple custom rules for a single language. You can also use the `-p|--path` parameter to specify a directory that contains multiple JAR or XML files. To add one or more custom rules to multiple languages, use a separate `scanner rule add` command for each language. For example, to add a single JAR file for the Apex language: ``` sf scanner rule add --language apex --path path/to/your/File.jar (OR) sf scanner rule add -l apex -p path/to/your/File.jar ``` ### Replace these values: - `apex`: The language to evaluate the rules against. - `path/to/your/File.jar`: One or more paths to custom rule definitions. To add a directory path that contains multiple JAR/XML files for the same language: ``` sf scanner rule add --language apex --path path/to/your/files (OR) sf scanner rule add -l apex -p path/to/your/files ``` ### Replace these values: - `apex`: The language to evaluate the rules against. - `path/to/your/files`: One or more paths to custom rule definitions. To add multiple paths to files that are in different locations for the same language: ``` sf scanner rule add --language apex --path path/to/your/files,/another/path/Custom.jar,/yet/another/jar/lib (OR) sf scanner rule add -l apex -p path/to/your/files,/another/path/Custom.jar,/yet/another/jar/lib ``` ### Replace these values: - `apex`: The language to evaluate the rules against. - `path/to/your/files,/another/path/Custom.jar,/yet/another/jar/lib`: One or more paths to custom rule definitions. The command output indicates which JAR files were found and added to Code Analyzer. ### Run Rules After you add your rules to Code Analyzer with `scanner rule add`, run [`scanner rule list`] (../command-reference/list.md) to review the complete catalog of existing PMD rules and your latest additions. Your custom rules are displayed under the category names that you defined in your XML rule-definition files, and they’re ready to use. Run your custom rules using `scanner run` the same way you run PMD's built-in rules: `scanner run --category MyCustomCategory`. You don't need the `--pmdconfig` flag to run your custom rules. ### Remove Rules Remove custom rules from the catalog with the [`scanner rule remove`] (../command-reference/remove.md). The rules defined in the JAR/XML file that you specify with the `-p|--path` parameter are removed from the catalog. To bypass confirmation of the removal, use the `--force` parameter. ## See Also - [_PMD Source Code Analyzer Project_: Configuring Rules ](https://docs.pmd-code.org/latest/pmd_userdocs_configuring_rules.html) - [_PMD Source Code Analyzer Project_: Introduction to Writing PMD Rules](https://pmd.github.io/latest/pmd_userdocs_extending_writing_rules_intro.html) - [_PMD Source Code Analyzer Project_: Making rulesets](https://pmd.github.io/latest/pmd_userdocs_making_rulesets.html) - [_PMD Source Code Analyzer Project_: XML Rule Definition](https://pmd.github.io/latest/pmd_userdocs_extending_writing_rules_intro.html#xml-rule-definition) - [sf scanner rule add](https://developer.salesforce.com/docs/platform/salesforce-code-analyzer/command-reference/add.md) - [_Xpath_: Writing Xpath rules](https://pmd.github.io/latest/pmd_userdocs_extending_writing_xpath_rules.html)