1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
|
<?xml version="1.0" encoding="UTF-8"?>
<document xmlns="http://maven.apache.org/XDOC/2.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/XDOC/2.0 http://maven.apache.org/xsd/xdoc-2.0.xsd">
<head>
<title>Command Line</title>
<script type="text/javascript" src="https://ajax.googleapis.com/ajax/libs/jquery/2.1.3/jquery.min.js"/>
<script type="text/javascript" src="js/anchors.js"/>
<script type="text/javascript" src="js/google-analytics.js"/>
<link rel="icon" href="images/favicon.png" type="image/x-icon" />
<link rel="shortcut icon" href="images/favicon.ico" type="image/ico" />
</head>
<body>
<section name="Content">
<macro name="toc">
<param name="fromDepth" value="1"/>
<param name="toDepth" value="1"/>
</macro>
</section>
<section name="Description">
<p>
This document describes how to run Checkstyle using the command line
tool. The latest version of Checkstyle can be found at <a
href="http://checkstyle.sourceforge.net">http://checkstyle.sourceforge.net</a>.
This command line tool is included in the Checkstyle distribution.
</p>
</section>
<section name="Command line usage">
<p>
<source>
java -D<property>=<value> \
com.puppycrawl.tools.checkstyle.Main \
-c <configurationFile> \
[-f <format>] [-p <propertiesFile>] [-o <file>] \
[-t | --tree] [-T | --treeWithComments] [-J | treeWithJavadoc] [-j | --javadocTree] [-v] \
file...
</source>
</p>
<p>
Checkstyle will process the specified files and by default report
errors to standard out in plain format. Checkstyle requires a <a
href="config.html">configuration XML file</a> that configures the
checks to apply. Command line options are:
</p>
<ul>
<li>
<code>-c configurationFile</code> - specifies the location of the
file that defines the configuration modules. The location can either
be a filesystem location, or a <a href="http://docs.oracle.com/javase/8/docs/technotes/guides/lang/resources.html#res_names">name</a> passed to the
ClassLoader.getResource() method.
</li>
<li>
<code>-f format</code> - specify the output
format. Options are <code> "plain"</code> for the <a
href="apidocs/com/puppycrawl/tools/checkstyle/DefaultLogger.html">DefaultLogger</a>
and <code>"xml"</code> for the <a
href="apidocs/com/puppycrawl/tools/checkstyle/XMLLogger.html">XMLLogger</a>.
Defaults to <code>"plain"</code>.
</li>
<li>
<code>-p propertiesFile</code> - specify a
properties file to use.
</li>
<li>
<code>-o file</code> - specify the file to output
to.
</li>
<li>
<code>-t, --tree</code> - print Abstract Syntax Tree(AST) of the checked file. The option
cannot be used other options and requires exactly one file to run on to be specified.
</li>
<li>
<code>-T, --treeWithComments</code> - print Abstract Syntax Tree(AST) with comment nodes of the checked file. The option
cannot be used other options and requires exactly one file to run on to be specified.
</li>
<li>
<code>-J, --treeWithJavadoc</code> - print Abstract Syntax Tree(AST) with Javadoc nodes and comment nodes
of the checked file. Attention that line number and columns will not be the same as it is a file due to the fact
that each javadoc comment is parsed separately from java file. The option cannot be used other options and requires
exactly one file to run on to be specified.
</li>
<li>
<code>-j, --javadocTree</code> - print Parse Tree of the Javadoc comment.
The file have to contain <b>only Javadoc comment content</b> without including '/**' and '*/' at the beginning and at the end respectively.
For example:
MyTestFile.javadoc
<source>
* Test method.
* @return true
</source>
The option
cannot be used other options and requires exactly one file to run on to be specified.
</li>
<li>
<code>-d, --debug</code> - Print all debug logging of CheckStyle utility.
</li>
<li>
<code>-e, --exclude excludedDirectory</code> - Directory to exclude from
CheckStyle. The directory can be the full, absolute path, or relative to the current path.
Multiple excludes are allowed.
</li>
<li>
<code>-x, --exclude-regexp excludedDirectoryPattern</code> - Directory pattern to exclude from
CheckStyle. Multiple excludes are allowed.
</li>
<li>
<code>-v</code> - print product version and exit. Any other option is ignored.
</li>
</ul>
<p>
Note that the <code>-n packageNamesFile</code>
option has been dropped for Checkstyle 5.0, because of
significant changes regarding package name file handling. See <a
href="config.html#Packages"/> for details.
</p>
<p>
Set the properties for <a href="config.html#Properties">expanded
property values</a> by either by assigning system properties using the
<code>-D<property>=<value></code> arguments to java or
specifying a property file using the <code>-p</code> option. If a
property file is specified, the system properties are ignored.
</p>
</section>
<section name="Download and Run">
<p>
It is possible to run Checkstyle directly from the JAR file using
the <code>-jar</code> option. Download latest <a href="http://downloads.sourceforge.net/project/checkstyle/checkstyle/${projectVersion}/checkstyle-${projectVersion}-all.jar">
checkstyle-${projectVersion}-all.jar</a>.
An example of run would be:
<source class="wrap-content">
java -jar checkstyle-${projectVersion}-all.jar -c /sun_checks.xml MyClass.java
java -jar checkstyle-${projectVersion}-all.jar -c /google_checks.xml MyClass.java
</source>
It is recommended to use configuration files that are embedded in jar files, but latest configuration files are there:
<a href="https://raw.githubusercontent.com/checkstyle/checkstyle/master/src/main/resources/sun_checks.xml">sun_checks.xml</a>
<a href="https://raw.githubusercontent.com/checkstyle/checkstyle/master/src/main/resources/google_checks.xml">google_checks.xml</a>
</p>
<p>
To run <a href="writingchecks.html#The_Checkstyle_SDK_Gui">Checkstyle UI viewer</a> for AST tree directly from the JAR file using
the <code>-jar</code> option. Download latest <a href="http://downloads.sourceforge.net/project/checkstyle/checkstyle/${projectVersion}/checkstyle-${projectVersion}-all.jar">
checkstyle-${projectVersion}-all.jar</a>.
An example of run would be (path to java file is optional):
<source class="wrap-content">
java -cp checkstyle-${projectVersion}-all.jar com.puppycrawl.tools.checkstyle.gui.Main MyClass.java
</source>
</p>
</section>
<section name="Run after compilation">
<p>
Download and compile:
<source class="wrap-content">
git clone https://github.com/checkstyle/checkstyle.git
cd checkstyle
mvn clean compile
</source>
Run validation with arguments:
<source class="wrap-content">
mvn exec:java -Dexec.mainClass="com.puppycrawl.tools.checkstyle.Main" -Dexec.args="-c /sun_checks.xml src/main/java "
</source>
Run UI application for file :
<source class="wrap-content">
mvn exec:java -Dexec.mainClass="com.puppycrawl.tools.checkstyle.gui.Main" -Dexec.args="src/main/java/com/puppycrawl/tools/checkstyle/Checker.java"
</source>
Build all jars, and launch CLI from new build:
<source class="wrap-content">
mvn clean package -Passembly
java -jar target/checkstyle-X.X-SNAPSHOT-all.jar -c /sun_checks.xml MyClass.java
</source>
</p>
</section>
<section name="Usage by Classpath update">
<p>
The easiest way is to include
<a href="http://downloads.sourceforge.net/project/checkstyle/checkstyle/${projectVersion}/checkstyle-${projectVersion}-all.jar">checkstyle-${projectVersion}-all.jar</a> in the
<a href="http://docs.oracle.com/javase/8/docs/technotes/tools/windows/classpath.html#sthref10">classpath</a>. Alternatively, you must include the
<code>compile</code> third party dependencies listed in
<a href="dependencies.html">Project Dependencies</a> in the
classpath.
<br/>
<br/>
<b>
Run checkstyle with configuration file at
<code>docs/sun_checks.xml</code> on a filesystem
</b>
</p>
<source class="wrap-content">
java com.puppycrawl.tools.checkstyle.Main -c docs/sun_checks.xml Check.java
</source>
<p>
<b>
Run checkstyle with configuration file
<code>docs/sun_checks.xml</code> on all Java files in a directory
</b>
</p>
<source class="wrap-content">
java com.puppycrawl.tools.checkstyle.Main -c docs/sun_checks.xml src/
</source>
<p>
<b>
Run checkstyle with configuration file
<code>docs/sun_checks.xml</code> on a file and provide a system
property
</b>
</p>
<source class="wrap-content">
java -Dcheckstyle.cache.file=target/cachefile com.puppycrawl.tools.checkstyle.Main -c docs/sun_checks.xml Check.java
</source>
<p>
<b>
Run checkstyle with configuration file
<code>docs/sun_checks.xml</code> on a file and use properties in a
file
</b>
</p>
<source class="wrap-content">
java com.puppycrawl.tools.checkstyle.Main -c docs/sun_checks.xml -p myCheckstyle.properties Check.java
</source>
<p>
<b>
Run checkstyle with configuration file
<code>docs/sun_checks.xml</code> on a file and output to a file in
XML format
</b>
</p>
<source class="wrap-content">
java com.puppycrawl.tools.checkstyle.Main -c docs/sun_checks.xml -f xml -o build/checkstyle_errors.xml Check.java
</source>
<p>
<b>
Run checkstyle with <a href="extending.html">custom module(s)
(Root module, Checks, etc)</a> in configuration file:
</b>
</p>
<source class="wrap-content">
java -classpath MyCustom.jar;checkstyle-${projectVersion}-all.jar com.puppycrawl.tools.checkstyle.Main -c config.xml Check.java
</source>
<p>
<b>Note</b>: Custom modules should be specified with the class'
<a href="writingchecks.html#Integrate_your_Check">full classpath</a>
in the configuration file and the compiled class be located in the custom
JAR for Checkstyle to find.
</p>
</section>
</body>
</document>
|
