Debian Codegraph @

animal-sniffer-ant-tasks/src/site/apt/usage.apt.vm

raw
1 ~~ The MIT License
2 ~~
3 ~~ Copyright (c) 2009 codehaus.org.
4 ~~
5 ~~ Permission is hereby granted, free of charge, to any person obtaining a copy
6 ~~ of this software and associated documentation files (the "Software"), to deal
7 ~~ in the Software without restriction, including without limitation the rights
8 ~~ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9 ~~ copies of the Software, and to permit persons to whom the Software is
10 ~~ furnished to do so, subject to the following conditions:
11 ~~
12 ~~ The above copyright notice and this permission notice shall be included in
13 ~~ all copies or substantial portions of the Software.
14 ~~
15 ~~ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16 ~~ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17 ~~ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18 ~~ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19 ~~ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20 ~~ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
21 ~~ THE SOFTWARE.
22 ~~
23
24 -----
25 Usage
26 -----
27 Stephen Connolly
28 ------
29 2009-11-05
30 ------
31
32 Usage
33
34 The ANT Tasks include tasks for checking classes against the signatures of an API as well as
35 goals for generating signatures of APIs.
36
37 * Basic Usage
38
39 ** Defining the ANT Tasks
40
41 Before you can use the Animal Sniffer ANT Tasks you need to inform ANT about these tasks.
42 There are several techniques for defining custom tasks in ANT. Our preferred technique (and the
43 technique that we will assume you use) is to use a namespace and the <<<antlib.xml>>> from within
44 the Animal Sniffer ANT Tasks jar file, for example:
45
46 ---
47 <project ... xmlns:as="antlib:org.codehaus.mojo.animal_sniffer">
48 ...
49 <typedef uri="antlib:org.codehaus.mojo.animal_sniffer">
50 <classpath path="lib/${pom.xml.project.artifactId}-${pom.xml.project.parent.version}.jar"/>
51 </typedef>
52 ...
53 </project>
54 ---
55
56 Note: if you want to use any of the other techniques for importing ANT tasks, we (Maven developers)
57 assume that you (ANT developer) know how to convert our examples into the technique you are using.
58 This namespace based techique is the way the authors of this document know.
59
60 ** Checking a classes against an API signature
61
62 In order to check your classes against an API signature, you use the <<<check-signature>>> task:
63
64 ---
65 <project ... xmlns:as="antlib:org.codehaus.mojo.animal_sniffer">
66 ...
67 <target ...>
68 ...
69 <as:check-signature signature=".../my-signature.sig">
70 <path path="classes"/>
71 </as:check-signature>
72 ...
73 </target>
74 ...
75 </project>
76 ---
77
78 The path provided will be recursively searched for jar files and class files, all of which will be
79 checked against the supplied signature.
80
81 When you run the <<<check-signature>>> task as in the above example, the task will fail if your
82 classes reference any class, method or field that is not either:
83
84 * in the signatures; or
85
86 * on the path you provided
87
88 []
89
90 If you have compiled your classes against a classpath that you have already verified against the signature
91 of your target platform, you can speed up the checking process by giving the <<<check-signature>>> task
92 the classpathRef of your compile classpath. For example, if you are checking a web application against signatures for
93 the Java EE Servlet specification, you might reference the classpath of the WEB-INF/lib folder when
94 checking your WEB-INF/classes path. The following example illustrates how to achieve this:
95
96 ---
97 <project ... xmlns:as="antlib:org.codehaus.mojo.animal_sniffer">
98 ...
99 <target ...>
100 ...
101 <as:check-signature signature=".../javaee-servlet.sig" classpathRef="webLibs">
102 <path path="build/web/WEB-INF/classes"/>
103 </as:check-signature>
104 ...
105 </target>
106 ...
107 </project>
108 ---
109
110 For more detailed examples of how to configure this task see:
111
112 * {{{./examples/checking-signatures.html} Checking signatures}}.
113
114 []
115
116 ** Generating API signatures
117
118 To generate the signatures of an API, simply invoke the <<<build-signatures>>> tasks providing
119 the path of the API you want to generate the signatures for, e.g.
120
121 ---
122 <project ... xmlns:animal-sniffer="antlib:org.codehaus.mojo.animal_sniffer">
123 ...
124 <target ...>
125 ...
126 <as:build-signatures destfile="dist/api.sig">
127 <path>
128 <fileset dir="classes"/>
129 <fileset dir="lib" includes="log4j.jar"/>
130 </path>
131 </as:build-signatures>
132 ...
133 </target>
134 ...
135 </project>
136 ---
137
138 For more detailed examples of how to configure this goal see:
139
140 * {{{./examples/generating-signatures.html}Generating signatures}}
141
142 []