        --------------------------------------------------
                      CodeNarc Ant Task
        --------------------------------------------------

CodeNarc - Ant Task
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

* Description
~~~~~~~~~~~~~

  The <<CodeNarc>> Ant Task is implemented by the <<<org.codenarc.ant.CodeNarcTask>>> class.

* Parameters
~~~~~~~~~~~~

*------------------------+----------------------------------------------------------------+------------------------+
| <<Attribute>>          | <<Description>>                                                | <<Required>>           |
*------------------------+----------------------------------------------------------------+------------------------+
| ruleSetFiles           | The paths to the Groovy or XML RuleSet definition files. This  | YES                    |
|                        | can be a single file path, or  multiple paths separated by     |                        |
|                        | commas. By default, the paths specified are relative to the    |                        |
|                        | classpath. But each path may be optionally prefixed by any     |                        |
|                        | of the valid java.net.URL prefixes, such as "file:" (to load   |                        |
|                        | from a relative or absolute filesystem path), or "http:".      |                        |
*------------------------+----------------------------------------------------------------+------------------------+
| maxPriority1Violations | The maximum number of priority 1 violations allowed before     | NO                     |
|                        | failing the build (throwing a <<<BuildException>>>).           |                        |
*------------------------+----------------------------------------------------------------+------------------------+
| maxPriority2Violations | The maximum number of priority 2 violations allowed before     | NO                     |
|                        | failing the build (throwing a <<<BuildException>>>).           |                        |
*------------------------+----------------------------------------------------------------+------------------------+
| maxPriority3Violations | The maximum number of priority 3 violations allowed before     | NO                     |
|                        | failing the build (throwing a <<<BuildException>>>).           |                        |
*------------------------+----------------------------------------------------------------+------------------------+


* Report Nested Element
~~~~~~~~~~~~~~~~~~~~~~~

  The <<report>> nested element defines the format and output file for the analysis report.

*----------------------+----------------------------------------------------------------+------------------------+
| <<Attribute>>        | <<Description>>                                                | <<Required>>           |
*----------------------+----------------------------------------------------------------+------------------------+
| type                 | The type of the output report. Must be either one of the       | Yes                    |
|                      | predefined type names: "html", "xml", "text", "console", "ide" |                        |
|                      | or else the fully-qualified class name                         |                        |
|                      | of a class (accessible on the classpath) that implements the   |                        |
|                      | <<<org.codenarc.report.ReportWriter>>> interface.              |                        |
*----------------------+----------------------------------------------------------------+------------------------+
| toFile <(Deprecated)>| The path and filename for the output report file.              | No                     |
|                      | This is deprecated. Use the \<option\> nested element instead. |                        |
*----------------------+----------------------------------------------------------------+------------------------+
| title <(Deprecated)> | The title for the output report.                               | No                     |
|                      | This is deprecated. Use the \<option\> nested element instead. |                        |
*----------------------+----------------------------------------------------------------+------------------------+

  Notes:

    * The "ide" report <type> creates an <<<IdeTextReportWriter>>> and sets its <writeToStandardOut> property to <<<true>>>.
      The generated report includes IDE-compatible (Eclipse, Idea) hyperlinks to source code for violations.

    * The "console" report <type> creates a <<<TextReportWriter>>> and sets its <writeToStandardOut> property to <<<true>>>.


** Option Nested Element
~~~~~~~~~~~~~~~~~~~~~~~~

  The <<\<option\>>> element is a child of the <<\<report\>>> element and defines a
  report-specific option for a report. You specify the option <<name> and <<value>> as attributes
  within the <<\<option\>>> element. See the {{{Example}Example}} below.


* Fileset Nested Element
~~~~~~~~~~~~~~~~~~~~~~~

  At least one <<fileset>> nested element is required, and is used to specify the source files that
  <<CodeNarc>> should analyze. This is the standard Ant <FileSet>, and is quite powerful and flexible.
  See the {{{http://ant.apache.org/manual/index.html}Apache Ant Manual}} for more information on <FileSets>.


* {Example}
~~~~~~~~~~~

  Here is an example Ant XML build file.

+----------------------------------------------------------------------------------------
<taskdef name="codenarc" classname="org.codenarc.ant.CodeNarcTask"/>
<target name="runCodeNarc">
    <codenarc
            ruleSetFiles="rulesets/basic.xml,rulesets/exceptions.xml,rulesets/imports.xml"
            maxPriority1Violations="0">

        <report type="html">
            <option name="outputFile" value="reports/CodeNarcAntReport.html" />
            <option name="title" value="My Sample Code" />
        </report>

        <fileset dir="src">
            <include name="**/*.groovy"/>
        </fileset>
    </codenarc>
</target>
+----------------------------------------------------------------------------------------

  Things to note:

    * Three <RuleSet> files are specified (<basic>, <exceptions> and <imports>).

    * The <fileset> specifies that all ".groovy" files are analyzed.

    * Remember that you need the <<log4j>> jar (and a "log4j.properties" file) on the classpath.


* Logging and Troubleshooting
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

  Be sure to have a "log4j.properties" or "log4j.xml" file on the classpath so that any errors are logged.

