From 80d99744ee72dff928ef4f316d51e6b54b027296 Mon Sep 17 00:00:00 2001 From: Andreas Dangel Date: Fri, 21 Jul 2017 22:47:32 +0200 Subject: [PATCH] [doc] Add pages from old "usage" section --- docs/pages/pmd/userdocs/pmd_tools.md | 2 + docs/pages/pmd/userdocs/pmd_userdocs_ant.md | 323 ++++++++++++++++++++ docs/pages/pmd/userdocs/pmd_userdocs_ci.md | 26 ++ 3 files changed, 351 insertions(+) create mode 100644 docs/pages/pmd/userdocs/pmd_userdocs_ant.md create mode 100644 docs/pages/pmd/userdocs/pmd_userdocs_ci.md diff --git a/docs/pages/pmd/userdocs/pmd_tools.md b/docs/pages/pmd/userdocs/pmd_tools.md index 9eb55ef854..04d7609085 100644 --- a/docs/pages/pmd/userdocs/pmd_tools.md +++ b/docs/pages/pmd/userdocs/pmd_tools.md @@ -7,4 +7,6 @@ folder: pmd/userdocs * IDE plugins * build tool plugins + * [Ant Task Usage](/pmd_userdocs_ant.html) +* [Continuous Integrations plugins](/pmd_userdocs_ci.html) * GUIs diff --git a/docs/pages/pmd/userdocs/pmd_userdocs_ant.md b/docs/pages/pmd/userdocs/pmd_userdocs_ant.md new file mode 100644 index 0000000000..2997527ad2 --- /dev/null +++ b/docs/pages/pmd/userdocs/pmd_userdocs_ant.md @@ -0,0 +1,323 @@ +--- +title: Ant Task Usage +sidebar: pmd_sidebar +permalink: pmd_userdocs_ant.html +folder: pmd/userdocs +--- + +## PMD + +### Description + +Runs a set of static code analysis rules on some source code files and generates a list of problems found. + +### Parameters + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
AttributeDescriptionRequired
rulesetfiles + A comma delimited list of ruleset files ('rulesets/java/basic.xml,rulesets/java/design.xml'). + If you write your own ruleset files, you can put them on the classpath and plug them in here. + Yes, unless the ruleset nested element is used
failonerrorWhether or not to fail the build if any errors occur while processing the filesNo
failOnRuleViolationWhether or not to fail the build if PMD finds any problemsNo
minimumPriorityThe rule priority threshold; rules with lower priority than they will not be usedNo
shortFilenamesPlaces truncated filenames in the report. This can reduce your report file size by 15%-20%.No
failuresPropertyNameA property name to plug the number of rule violations into when the task finishesNo
encodingThe character set encoding (e.g. UTF-8) to use when reading the source code filesNo
suppressMarkerThe series of characters to use to tell PMD to skip lines - the default is NOPMD.No
maxRuleViolations + Whether or not to fail the build if PMD finds more than the value of this attribute. + Note that setting this attribute does not require to set the failOnRuleViolation to true. + No
cacheLocation + The location of the analysis cache file to be used. + The cache can greatly improve analysis time without loosing analysis quality. + It's use is strongly recommended. + No
+ + +`formatter` nested element - specifies the format of and the files to which the report is written. + + + + + + + + + + + + + + + + + + + + + + +
NameValues
typexml,ideaj,textcolor,text,textpad,emacs,csv,html,xslt,yahtml,summaryhtml,vbhtml,codeclimate
showSuppressedWhether to show suppressed warnings; "false" is the default.
toFileA filename to which to write the report
toConsoleWhether to output the report to the console; "false" is the default.
+

The formatter element can contain nested param elements to configure the formatter in detail, e.g.

+
+
encoding
+
Specifies the encoding to be used in the generated report (only honored when used with `toFile`). When rendering `toConsole` PMD will automatically detect the terminal's encoding and use it, unless the output is being redirected / piped, in which case `file.encoding` is used. See example below.
+
linkPrefix
+
Used for linking to online HTMLized source (like this). See example below.
+
linePrefix
+
Used for linking to online HTMLized source (like this). See example below.
+
+
+ + +`classpath` nested element - useful for specifying custom rule. More details on the `classpath` +element are in the Ant documentation [here](http://ant.apache.org/manual/using.html#path) and there's +an example below. + +`auxclasspath` nested element - extra classpath used for Type Resolution rules. + +`sourceLanguage` nested element - specify which language (Java, Ecmascript, XML,...) +and the associated version (1.5, 1.6,...) + +`ruleset` nested element - another way to specify rulesets. Here's an example: + + + + + + rulesets/java/design.xml + java-basic + + + + + + + + + +### Language version selection + +The specific version of a language to be used for parsing is selected via the `sourceLanguage` +nested element. Possible values are: + + + + + + + + + + + + + + + + + + +### Postprocessing the report file with XSLT + +Several folks (most recently, Wouter Zelle) have written XSLT scripts +which you can use to transform the XML report into nifty HTML. To do this, +make sure you use the XML formatter in the PMD task invocation, i.e.: + + + + + +Then, after the end of the PMD task, do this: + + + +### Examples + +Running one ruleset to produce a HTML report (and printing the report to the console as well) using a file cache + + + + + + + + + + + + + +Running multiple rulesets to produce an XML report with the same analysis cache + + + + + + + + + + + + + +Using a custom renderer + + + + + + + + + + + + +Using a classpath reference in the taskdef + + + + + + + + + + + + + + + + + + + +Getting verbose output + + [tom@hal bin]$ ant -v pmd + Apache Ant version 1.6.2 compiled on July 16 2004 + Buildfile: build.xml + Detected Java version: 1.4 in: /usr/local/j2sdk1.4.2_03/jre + Detected OS: Linux + parsing buildfile build.xml with URI = file:/home/tom/data/pmd/pmd/bin/build.xml + Project base dir set to: /home/tom/data/pmd/pmd + Build sequence for target `pmd' is [pmd] + Complete build sequence is [pmd, copy, cppjavacc, cpd, delete, + compile, clean, jar, dist, cpdjnlp, jjtree, javadoc, test, tomserver] + + pmd: + [pmd] Using the normal ClassLoader + [pmd] Using these rulesets: rulesets/java/imports.xml + [pmd] Using rule DontImportJavaLang + [pmd] Using rule UnusedImports + [pmd] Using rule ImportFromSamePackage + [pmd] Using rule DuplicateImports + [pmd] Processing file /usr/local/java/src/java/lang/ref/Finalizer.java + [pmd] Processing file /usr/local/java/src/java/lang/ref/FinalReference.java + [pmd] Processing file /usr/local/java/src/java/lang/ref/PhantomReference.java + [pmd] Processing file /usr/local/java/src/java/lang/ref/Reference.java + [pmd] Processing file /usr/local/java/src/java/lang/ref/ReferenceQueue.java + [pmd] Processing file /usr/local/java/src/java/lang/ref/SoftReference.java + [pmd] Processing file /usr/local/java/src/java/lang/ref/WeakReference.java + [pmd] 0 problems found + + BUILD SUCCESSFUL + Total time: 2 seconds + [tom@hal bin]$ + +An HTML report with the "linkPrefix" gizmo + + + + + + + + + + + + + +An HTML report with the "linePrefix" gizmo + + + + + + + + + + + + + +### Memory Usage + +Memory usage has been reduced significantly starting with the PMD 4.0 release. +When testing all Java rules on the jdk 1.6 source code (about 7000 classes), +the allocated heap space does not go over 60M. + +However, on very large projects, the Ant task may still fail with a OutOfMemoryError. +To prevent this from happening, increase the maximum memory usable by ant using the ANT_OPTS variable +(adjust the size according to your available memory): + +On Windows: + + set ANT_OPTS=-Xmx1024m -Xms512m + +On Linux + + export ANT_OPTS="-Xmx1024m -Xms512m" diff --git a/docs/pages/pmd/userdocs/pmd_userdocs_ci.md b/docs/pages/pmd/userdocs/pmd_userdocs_ci.md new file mode 100644 index 0000000000..900ee29edc --- /dev/null +++ b/docs/pages/pmd/userdocs/pmd_userdocs_ci.md @@ -0,0 +1,26 @@ +--- +title: Continuous Integrations plugins +sidebar: pmd_sidebar +permalink: pmd_userdocs_ci.html +folder: pmd/userdocs +--- + +## Introduction + +PMD can be integrate through some of the Continuous Integration tools that exist now. +Here is a list of known (to us) plugin to do so. + +## Hudson Plugin + +Hafner Ullrich has developed a [PMD plugin][hudsonplugin] for Hudson. +Please check the plugin homepage for more info. + +[hudsonplugin]: http://hudson.gotdns.com/wiki/display/HUDSON/PMD+Plugin + +## Continuum + +Continous does not have a plugin for PMD per see, but can failed the build according to the +result of the PMD maven plugin. + + +