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