You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
80 lines
2.7 KiB
80 lines
2.7 KiB
7 months ago
|
Auto Common Utilities
|
||
|
|
========
|
||
|
|
|
||
|
|
## Overview
|
||
|
|
|
||
|
|
The Auto project has a set of common utilities to help ease use of the annotation processing
|
||
|
|
environment.
|
||
|
|
|
||
|
|
## Utility classes of note
|
||
|
|
|
||
|
|
* MoreTypes - utilities and Equivalence wrappers for TypeMirror and related subtypes
|
||
|
|
* MoreElements - utilities for Element and related subtypes
|
||
|
|
* SuperficialValidation - very simple scanner to ensure an Element is valid and free from
|
||
|
|
distortion from upstream compilation errors
|
||
|
|
* Visibility - utilities for working with Elements' visibility levels (public, protected, etc.)
|
||
|
|
* BasicAnnotationProcessor/ProcessingStep - simple types that
|
||
|
|
- implement a validating annotation processor
|
||
|
|
- defer invalid elements until later
|
||
|
|
- break processor actions into multiple steps (which may each handle different annotations)
|
||
|
|
|
||
|
|
## Usage/Setup
|
||
|
|
|
||
|
|
Auto common utilities have a standard [Maven](http://maven.apache.org) setup which can also be
|
||
|
|
used from Gradle, Ivy, Ant, or other systems which consume binary artifacts from the central Maven
|
||
|
|
binary artifact repositories.
|
||
|
|
|
||
|
|
```xml
|
||
|
|
<dependency>
|
||
|
|
<groupId>com.google.auto</groupId>
|
||
|
|
<artifactId>auto-common</artifactId>
|
||
|
|
<version>1.0-SNAPSHOT</version> <!-- or use a known release version -->
|
||
|
|
</dependency>
|
||
|
|
```
|
||
|
|
|
||
|
|
## Processor Resilience
|
||
|
|
|
||
|
|
Auto Common Utilities is used by a variety of annotation processors in Google and new versions
|
||
|
|
may have breaking changes. Users of auto-common are urged to use
|
||
|
|
[shade](https://maven.apache.org/plugins/maven-shade-plugin/) or
|
||
|
|
[jarjar](https://code.google.com/p/jarjar/) (or something similar) in packaging their processors
|
||
|
|
so that conflicting versions of this library do not adversely interact with each other.
|
||
|
|
|
||
|
|
For example, in a Maven build you can repackage `com.google.auto.common` into
|
||
|
|
`your.processor.shaded.auto.common` like this:
|
||
|
|
|
||
|
|
```xml
|
||
|
|
<project>
|
||
|
|
<!-- your other config -->
|
||
|
|
<build>
|
||
|
|
<plugins>
|
||
|
|
<plugin>
|
||
|
|
<artifactId>maven-shade-plugin</artifactId>
|
||
|
|
<executions>
|
||
|
|
<execution>
|
||
|
|
<phase>package</phase>
|
||
|
|
<goals>
|
||
|
|
<goal>shade</goal>
|
||
|
|
</goals>
|
||
|
|
<configuration>
|
||
|
|
<artifactSet>
|
||
|
|
<excludes>
|
||
|
|
<!-- exclude dependencies you don't want to bundle in your processor -->
|
||
|
|
</excludes>
|
||
|
|
</artifactSet>
|
||
|
|
<relocations>
|
||
|
|
<relocation>
|
||
|
|
<pattern>com.google.auto.common</pattern>
|
||
|
|
<shadedPattern>your.processor.shaded.auto.common</shadedPattern>
|
||
|
|
</relocation>
|
||
|
|
</relocations>
|
||
|
|
</configuration>
|
||
|
|
</execution>
|
||
|
|
</executions>
|
||
|
|
</plugin>
|
||
|
|
</plugins>
|
||
|
|
</build>
|
||
|
|
</project>
|
||
|
|
```
|
||
|
|
|