How uber/nullaway works
This project is a multi-module, Gradle-based tool designed to work as an Error Prone plugin for annotation-based null checking in Java. In other words, NullAway is a tool that integrates into the Java compilation process (via Error Prone) to catch potential null pointer dereferences by using annotations like @Nullable. Along with its core checking functionality, the project includes ancillary modules for generating library models, automatically inferring annotations (via jar-infer), performance benchmarks (via JMH), and example/sample applications/libraries for demonstration and integration testing.
Main Components
• NullAway Core – This is the heart of the tool. It is implemented under the “nullaway” module and includes the dataflow analysis, error reporting, and integration with Error Prone.
• Annotation API – Found in the “annotations” directory, this module defines the custom annotations (e.g., @EnsuresNonNull, @RequiresNonNull) used by NullAway.
• Jar Infer Modules – Located under the “jar-infer” directory, these provide automatic inference of nullability for compiled libraries. This component includes separate submodules for different Android SDK versions as well as the CLI and core library.
• Library Model Generator – Under “library-model”, this component generates models representing library APIs and their nullability behavior.
• Benchmarking and Testing – The “jmh” module contains benchmarks to measure the performance overhead of NullAway, while there are several test directories (e.g., “guava-recent-unit-tests”, “jdk-recent-unit-tests”, “nullaway/src/test/”, etc.) for integration and unit testing.
• Sample Applications and Libraries – Modules like “sample-app”, “sample-library-model”, “sample” provide sample usage, illustrating how end users integrate NullAway into their projects.
• Build and Configuration Infrastructure – Includes Gradle scripts, settings (build.gradle, settings.gradle), and CI/CD configurations (GitHub workflows) that orchestrate builds, tests, code coverage, and releases.
Relationships and Data/Control Flows
• How “NullAway Core” integrates with the Error Prone framework (marked as an external component) to intercept the compilation process and analyze code.
• Interaction between the “Jar Infer” modules and “NullAway Core”: inferred nullability models from jar-infer can be fed into the NullAway pipeline.
• “Library Model Generator” with both “NullAway Core” and sample/library modules to demonstrate how library nullability models are integrated into static analysis.
• A block for “Configuration & Build Scripts” to indicate that these files set up options (such as -Xep:NullAway:ERROR, options.errorprone, etc.) for processing by the NullAway tool during builds.
Architectural Patterns and Design Principles
• Modular Design – Each primary functionality is isolated in its own module (e.g., core analysis, annotation definitions, model generation) to allow for independent development, testing, and reuse.
• Plugin Architecture – NullAway works as a plugin to Error Prone, leveraging existing compiler checking capabilities while extending its functionality.
• Testability and Performance – Multiple test modules and the inclusion of benchmarking (via JMH) emphasize the importance of verifying behavior and ensuring performance remains acceptable.
• Main modules: NullAway core, annotations, jar-infer (with its submodules such as android-jarinfer-models for various SDKs, CLI, and lib), library-model generator, benchmarking (jmh), sample apps/libraries, and test suites.
• Clearly distinguish external dependencies (Error Prone, Gradle, third-party annotations like JSpecify or AndroidX) from in-house components.
• Build orchestration and CI/CD (from the .github folder configurations and Gradle scripts) which manage tests, benchmarks, and releases.