README.md
1Auto Common Utilities
2========
3
4## Overview
5
6The Auto project has a set of common utilities to help ease use of the annotation processing
7environment.
8
9## Utility classes of note
10
11 * MoreTypes - utilities and Equivalence wrappers for TypeMirror and related subtypes
12 * MoreElements - utilities for Element and related subtypes
13 * SuperficialValidation - very simple scanner to ensure an Element is valid and free from
14 distortion from upstream compilation errors
15 * Visibility - utilities for working with Elements' visibility levels (public, protected, etc.)
16 * BasicAnnotationProcessor/ProcessingStep - simple types that
17 - implement a validating annotation processor
18 - defer invalid elements until later
19 - break processor actions into multiple steps (which may each handle different annotations)
20
21## Usage/Setup
22
23Auto common utilities have a standard [Maven](http://maven.apache.org) setup which can also be
24used from Gradle, Ivy, Ant, or other systems which consume binary artifacts from the central Maven
25binary artifact repositories.
26
27```xml
28<dependency>
29 <groupId>com.google.auto</groupId>
30 <artifactId>auto-common</artifactId>
31 <version>1.0-SNAPSHOT</version> <!-- or use a known release version -->
32</dependency>
33```
34
35## Processor Resilience
36
37Auto Common Utilities is used by a variety of annotation processors in Google and new versions
38may have breaking changes. Users of auto-common are urged to use
39[shade](https://maven.apache.org/plugins/maven-shade-plugin/) or
40[jarjar](https://code.google.com/p/jarjar/) (or something similar) in packaging their processors
41so that conflicting versions of this library do not adversely interact with each other.
42
43For example, in a Maven build you can repackage `com.google.auto.common` into
44`your.processor.shaded.auto.common` like this:
45
46```xml
47<project>
48 <!-- your other config -->
49 <build>
50 <plugins>
51 <plugin>
52 <artifactId>maven-shade-plugin</artifactId>
53 <executions>
54 <execution>
55 <phase>package</phase>
56 <goals>
57 <goal>shade</goal>
58 </goals>
59 <configuration>
60 <artifactSet>
61 <excludes>
62 <!-- exclude dependencies you don't want to bundle in your processor -->
63 </excludes>
64 </artifactSet>
65 <relocations>
66 <relocation>
67 <pattern>com.google.auto.common</pattern>
68 <shadedPattern>your.processor.shaded.auto.common</shadedPattern>
69 </relocation>
70 </relocations>
71 </configuration>
72 </execution>
73 </executions>
74 </plugin>
75 </plugins>
76 </build>
77</project>
78```
79
80