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
|
<?xml version="1.0" encoding="ISO-8859-1"?>
<document>
<properties>
<title>Clirr Ant Task</title>
<author>Lars Khne</author>
</properties>
<body>
<section name="Running Clirr as an Ant Task">
<p>
The clirr-core module contains an
<a href="http://ant.apache.org">Ant</a> task.
The following text assumes that you are familiar with Ant. To run clirr, you typically
</p>
<ul>
<li>compile the current version of the library you want to check, resulting in one or more jar file</li>
<li>tell ant about the clirr ant task</li>
<li>download the compatibility baseline release of your software from a central location via http
(if it is not available in your local filesystem already)</li>
<li>run the clirr task</li>
</ul>
<p>
To do this you will need an ant snippet similar to the following:
</p>
<source>
<target name="checkbinarycompatibility" depends="build">
<!-- buildtools.classpath should either contain
clirr-core-uber.jar or alternatively
clirr-core.jar and the libraries it depends on -->
<taskdef
classpathref="buildtools.classpath"
resource="clirrtask.properties"/>
<property
name="jar.baseline"
value="${ant.project.name}-${compatibility.baseline.version}.jar"/>
<get
src="${url.libbase}/${ant.project.name}/${jar.baseline}"
dest="build/tmp/${jar.baseline}"/>
<clirr>
<origfiles dir="build/tmp" includes="${jar.baseline}"/>
<newfiles dir="build/lib" includes="${jar.buildresult}"/>
<!-- <formatter type="xml" outfile="build/clirr.xml" /> -->
<!-- TODO: example for 3rd party classpath -->
</clirr>
</target>
</source>
</section>
<section name="Parameters">
<table>
<tr>
<td>Attribute</td>
<td>Description</td>
<td>Required</td>
<td>Default</td>
</tr>
<tr>
<td>failOnBinWarning</td>
<td>Whether task execution should fail (break the build) on warnings
about binary compatibility issues</td>
<td>No</td>
<td>No</td>
</tr>
<tr>
<td>failOnBinError</td>
<td>Whether task execution should fail (break the build) on binary
compatibility errors</td>
<td>No</td>
<td>Yes</td>
</tr>
<tr>
<td>failOnSrcWarning</td>
<td>Whether task execution should fail (break the build) on warnings
about source code compatibility issues</td>
<td>No</td>
<td>No</td>
</tr>
<tr>
<td>failOnSrcError</td>
<td>Whether task execution should fail (break the build) on source
compatibility errors</td>
<td>No</td>
<td>Yes</td>
</tr>
</table>
</section>
<section name="Parameters specified as nested elements">
<section name="newFiles">
<p>
A
<a href="http://ant.apache.org/manual/CoreTypes/fileset.html">FileSet</a>
that describes the current version that should be checked against
the compatibility baseline.
</p>
<p>
Clirr works with FileSets instead of individual jar files to allow
splitting up or combining library distributions. An example is log4j,
presumably the 1.3.0 release will split up the earlier log4j.jar
into several jar files.
</p>
</section>
<section name="origFiles">
<p>
A
<a href="http://ant.apache.org/manual/CoreTypes/fileset.html">FileSet</a>
that describes the compatibility baseline to check against.
</p>
</section>
<section name="newClassPath">
<p>
The 3rd party
<a href="http://ant.apache.org/manual/using.html#path">ClassPath</a>
that is referenced by the checked library version (newFiles). Any
class or interface that occurs as a baseclass, parameter type or method return type
must be included here.
</p>
</section>
<section name="origClassPath">
<p>
The 3rd party
<a href="http://ant.apache.org/manual/using.html#path">ClassPath</a>
that is referenced by the compatibility baseline version (origFiles). Any
class or interface that occurs as a baseclass, parameter type or method return type
must be included here.
</p>
<p>
Often the origClassPath is the same as the newClassPath.
In these cases you can specify these paths using the refid attribute to avoid
duplicating the classpath information. Please refer to the
<a href="http://ant.apache.org/manual/using.html#path">ant manual</a>
for details.
</p>
</section>
<section name="formatter">
<p>
A formatter that generates Clirr output. Multiple formatters can be specified.
Available attributes for each formatter element:
</p>
<table>
<tr>
<td>Attribute</td>
<td>Description</td>
<td>Required</td>
<td>Default</td>
</tr>
<tr>
<td>type</td>
<td>The formatter type. Available types are <em>plain</em> and <em>xml</em></td>
<td>No</td>
<td>plain</td>
</tr>
<tr>
<td>outfile</td>
<td>The file to write to. If not specified, output is written to stdout</td>
<td>No</td>
<td>stdout</td>
</tr>
</table>
</section>
<p>
If no formatter is specified, Clirr will write it's findings to stdout in plain format.
</p>
</section>
<section name="apiclasses">
<p>
A
<a href="http://ant.apache.org/manual/CoreTypes/patternset.html">PatternSet</a>
that defines which classes form the API. By default all classes are included.
</p>
<p>
The API is often only a subset from the set of public classes in a jar file. For example,
the Eclipse project has
<a href="http://www.eclipse.org/articles/Article-API%20use/eclipse-api-usage-rules.html">package
naming conventions</a> that signal which classes must not
be used outside a module, even though they are technically public.
</p>
<p>
Example:
</p>
<source>
<clirr>
<origfiles dir="build/tmp" includes="${jar.baseline}"/>
<newfiles dir="build/lib" includes="${jar.buildresult}"/>
<apiclasses>
<exclude name="**/internal/**"/>
<exclude name="**/examples/**"/>
<exclude name="**/tests/**"/>
</apiclasses>
</clirr>
</source>
</section>
</body>
</document>
|
