aosp12/external/auto/common

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 setup which can also be used from Gradle, Ivy, Ant, or other systems which consume binary artifacts from the central Maven binary artifact repositories.

<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 or 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:

<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>