src/site/apt/usage.apt.vm

 ------
 Usage
 ------
 Maria Odea Ching
 ------
 2006-07-21
 ------

~~ Licensed to the Apache Software Foundation (ASF) under one
~~ or more contributor license agreements.  See the NOTICE file
~~ distributed with this work for additional information
~~ regarding copyright ownership.  The ASF licenses this file
~~ to you under the Apache License, Version 2.0 (the
~~ "License"); you may not use this file except in compliance
~~ with the License.  You may obtain a copy of the License at
~~
~~   http://www.apache.org/licenses/LICENSE-2.0
~~
~~ Unless required by applicable law or agreed to in writing,
~~ software distributed under the License is distributed on an
~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
~~ KIND, either express or implied.  See the License for the
~~ specific language governing permissions and limitations
~~ under the License.

~~ NOTE: For help with the syntax of this file, see:
~~ http://maven.apache.org/doxia/references/apt-format.html


Usage

 The following examples describe the basic usage of the Checkstyle Plugin.

* Generate Checkstyle Report As Part of the Project Reports

  To generate the Checkstyle report as part of the Project Reports, add the
  Checkstyle Plugin in the <<<\<reporting\>>>> section
  of your <<<pom.xml>>>.

+-----+
<project>
  ...
   <reporting>
      <plugins>
        <plugin>
          <groupId>org.apache.maven.plugins</groupId>
          <artifactId>maven-checkstyle-plugin</artifactId>
          <version>${project.version}</version>
          <reportSets>
            <reportSet>
              <reports>
                <report>checkstyle</report>
              </reports>
            </reportSet>
          </reportSets>
        </plugin>
      </plugins>
    </reporting>
  ...
</project>
+-----+

  Then, execute the site phase to generate the report.

+-----+
mvn site
+-----+

* Generate Checkstyle Report As Standalone

  You can also generate the Checkstyle report by explicitly executing the <<<checkstyle:checkstyle>>> goal from the
  command line. You are not required to specify the Checkstyle Plugin in your
  <<<pom.xml>>> unless you want to use a specific configuration.

+-----+
mvn checkstyle:checkstyle
+-----+

* Checking for Violations as Part of the Build

  If you want to report to the console or fail
  the build, you must add an execution of <<<checkstyle::check>>> to the <<<\<build\>>>> element
  and configure any options that you need.

  Options you set in the <<<\<reporting\>>>> element do not have any effect on executions in the <<<\<build\>>>> element.

  Note that the phase that <<<checkstyle::check>>> is bound to is very important.  If bound to the validate phase, it would check the code prior to compiling the code.  If the code is invalid, the parsing errors reported by checkstyle may be different than what would be expected from the javac compiler.  However, it's guaranteed to run.   Another popular option is to bind it to the verify phase which would run much later (and allow the javac compiler to flag invalid code prior to checkstyle).   However, if developers generally just use "mvn test" prior to pushing changes, checkstyle would not run as verify occurs after the test phase.

  For example:

+------+
 <plugin>
   <groupId>org.apache.maven.plugins</groupId>
   <artifactId>maven-checkstyle-plugin</artifactId>
   <version>${project.version}</version>
   <configuration>
     <configLocation>checkstyle.xml</configLocation>
     <encoding>UTF-8</encoding>
     <consoleOutput>true</consoleOutput>
     <failsOnError>true</failsOnError>
     <linkXRef>false</linkXRef>
   </configuration>
   <executions>
     <execution>
       <id>validate</id>
       <phase>validate</phase>
       <goals>
         <goal>check</goal>
       </goals>
     </execution>
   </executions>
 </plugin>
+------+