Configuration

Command-Line Options

The NullAway checker takes multiple configuration flags, in the format of Error Prone's Command-Line Flags. It will throw an error immediately upon loading if the -XepOpt:NullAway:AnnotatedPackages flag is not specified.

The following flags are currently supported; each of them can take multiple values as a comma separated list:

• -XepOpt:NullAway:AnnotatedPackages=...

The list of packages that should be considered properly annotated according to the NullAway convention (every possibly null parameter / return / field annotated @Nullable). E.g., -XepOpt:NullAway:AnnotatedPackages=com.foo,org.bar.

• -XepOpt:NullAway:UnannotatedSubPackages=...

A list of subpackages to be excluded from the AnnotatedPackages list. E.g., if all code under com.foo packages is properly annotated except for code under com.foo.baz, you could use the options -XepOpt:NullAway:AnnotatedPackages=com.foo -XepOpt:NullAway:UnannotatedSubPackages=com.foo.baz.

• -XepOpt:NullAway:KnownInitializers=...

The fully qualified name (without argument's, e.g. android.app.Activity.onCreate) of those methods from third-party libraries that NullAway should treat as initializers (equivalent to being annotated with an @Initializer annotation).

• -XepOpt:NullAway:ExcludedClassAnnotations=...

A list of annotations that cause classes to be excluded from nullability analysis. Note that while NullAway does not analyze the code of these classes, it still assumes the APIs are annotated correctly when analyzing callers into methods of the classes.

• -XepOpt:NullAway:ExcludedClasses=...

A list of classes to be excluded from the nullability analysis. Note that while NullAway does not analyze the code of these classes, it still assumes the APIs are annotated correctly when analyzing callers into methods of the classes.

• -XepOpt:NullAway:ExcludedFieldAnnotations=...

A list of annotations that cause fields to be excluded from being checked for proper initialization (e.g. javax.inject.Inject).

• -XepOpt:NullAway:CustomInitializerAnnotations=...

A list of annotations that should be considered equivalent to @Initializer annotations, and thus mark methods as initializers (e.g. org.junit.Before and org.junit.BeforeClass, which are automatically added to this list by default). Note that any annotation with the simple name @Initializer, from any package, will be considered an initializer annotation, but names passed to this configuration option must be fully-qualified class names.

• -XepOpt:NullAway:ExternalInitAnnotations=...

A list of annotations for classes that are "externally initialized." Tools like the Cassandra Object Mapper do their own field initialization of objects with a certain annotation (like @Table), after invoking the zero-argument constructor. For any class annotated with an external-init annotation, we don't check that the zero-arg constructor initializes all non-null fields.

• -XepOpt:NullAway:TreatGeneratedAsUnannotated=...

If set to true, NullAway treats any class annotated with @Generated as if its APIs are unannotated when analyzing uses from other classes. It also does not perform analysis on the code inside @Generated classes. If you want to skip analysis of @Generated classes but the APIs are properly annotated for nullability, use the -XepOpt:NullAway:ExcludedClassAnnotations option instead. Defaults to false.

Library Models

In addition to these options, NullAway will look for any classes implementing the com.uber.nullaway.LibraryModels interface, in the annotation processor path, and consider those as plug-in models for third-party unannotated libraries. (We search for such classes using the ServiceLoader facility.) Models defined in such classes will be loaded in addition to the default models for common Java and Android libraries included with the checker itself. For documentation on writing such custom models, refer to the javadoc documentation for com.uber.nullaway.LibraryModels itself. Also see our sample library model for an example; it is pulled in and used by our sample Java module (see the build.gradle file).

Other Build Systems

Maven

Here is an example Maven build configuration that pulls in Error Prone and NullAway:

  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-compiler-plugin</artifactId>
        <version>3.5</version>
        <configuration>
          <compilerId>javac-with-errorprone</compilerId>
          <forceJavacCompilerUse>true</forceJavacCompilerUse>
          <source>1.8</source>
          <target>1.8</target>
          <showWarnings>true</showWarnings>
          <annotationProcessorPaths>
            <path>
               <groupId>com.uber.nullaway</groupId>
               <artifactId>nullaway</artifactId>
               <version>0.3.0</version>
            </path>
          </annotationProcessorPaths>
          <compilerArgs>
            <arg>-Xep:NullAway:ERROR</arg>
            <arg>-XepOpt:NullAway:AnnotatedPackages=com.uber</arg>
          </compilerArgs>
        </configuration>
        <dependencies>
          <dependency>
            <groupId>org.codehaus.plexus</groupId>
            <artifactId>plexus-compiler-javac-errorprone</artifactId>
            <version>2.8</version>
          </dependency>
          <!-- override plexus-compiler-javac-errorprone's dependency on
               Error Prone with the latest version -->
          <dependency>
            <groupId>com.google.errorprone</groupId>
            <artifactId>error_prone_core</artifactId>
            <version>2.1.3</version>
          </dependency>
        </dependencies>        
      </plugin>
  </build>

Other

The first step is to get Error Prone running on your build, as documented here. Then, you need to get the NullAway jar on the annotation processor path for the Javac invocations where Error Prone is running. Finally, you need to pass the appropriate compiler arguments to configure NullAway (at the least, the -XepOpt:NullAway:AnnotatedPackages option).