Debian Codegraph @

animal-sniffer-maven-plugin/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 2010-03-10
30 ------
31
32 Usage
33
34 The plugin offers goals for checking projects against the signatures of an API as well as
35 goals for generating signatures of APIs.
36
37 * Basic Usage
38
39 ** Checking a project against an API signature
40
41 In order to check your project against an API signature, you must configure your
42 <<<pom.xml>>> to reference the signature to check against:
43
44 ---
45 <project>
46 ...
47 <build>
48 ...
49 <plugins>
50 ...
51 <plugin>
52 <groupId>${project.groupId}</groupId>
53 <artifactId>${project.artifactId}</artifactId>
54 <version>${project.version}</version>
55 ...
56 <configuration>
57 ...
58 <signature>
59 <groupId>org.codehaus.mojo.signature</groupId>
60 <artifactId>java15</artifactId>
61 <version>1.0</version>
62 </signature>
63 ...
64 </configuration>
65 ...
66 </plugin>
67 ...
68 </plugins>
69 ...
70 </build>
71 ...
72 </project>
73 ---
74
75 The example above configures the signature for JRE 1.5. For a list of other ready-made signatures, please visit the
76 {{{http://mojo.codehaus.org/signatures/}Animal Scents subproject}}.
77
78 In order to check your project against the signature you have just configured, either
79 invoke the <<<animal-sniffer:check>>> goal directly, e.g.
80
81 ---
82 mvn animal-sniffer:check
83 ---
84
85 or to make the checks part of your build process add an execution to your
86 configuration, e.g.
87
88 ---
89 <project>
90 ...
91 <build>
92 ...
93 <plugins>
94 ...
95 <plugin>
96 <groupId>${project.groupId}</groupId>
97 <artifactId>${project.artifactId}</artifactId>
98 <version>${project.version}</version>
99 <executions>
100 ...
101 <execution>
102 <id>___id of execution___</id>
103 ...
104 <phase>test</phase>
105 ...
106 <goals>
107 <goal>check</goal>
108 </goals>
109 ...
110 </execution>
111 ...
112 </executions>
113 </plugin>
114 ...
115 </plugins>
116 ...
117 </build>
118 ...
119 </project>
120 ---
121
122 <<Note:>> If you are attaching the plugin to your build process, and you want to check against
123 multiple separate APIs (e.g. check against the Tomcat, JBoss, and Jetty servlet containers,
124 or check against multiple Java versions) then you will probably want to move the signature
125 configuration inside each of your multiple executions otherwise your project will be
126 checked against the union of all the signatures specified, which is probably not what you
127 want.
128
129 {{{./examples/checking-signatures.html} Some more detailed examples of the <<<check>>> goal}}.
130
131 ** Generating API signatures
132
133 To generate the signatures of an API, simply construct a project with the appropriate
134 dependencies exposed by the API and then add an execution of the <<<animal-sniffer:build>>>
135 goal to your project, e.g.
136
137 ---
138 <project>
139 ...
140 <build>
141 ...
142 <plugins>
143 ...
144 <plugin>
145 <groupId>${project.groupId}</groupId>
146 <artifactId>${project.artifactId}</artifactId>
147 <version>${project.version}</version>
148 <executions>
149 ...
150 <execution>
151 <id>___id of execution___</id>
152 ...
153 <phase>package</phase>
154 ...
155 <goals>
156 <goal>build</goal>
157 </goals>
158 ...
159 </execution>
160 ...
161 </executions>
162 </plugin>
163 ...
164 </plugins>
165 ...
166 </build>
167 ...
168 </project>
169 ---
170
171 For more detailed examples of how to configure this goal see:
172
173 * {{{./examples/generating-java-signatures.html}Generating signatures of the Java Runtime}}
174
175 * {{{./examples/generating-other-api-signatures.html}Generating signatures of other APIs}}
176
177 []