Technical Solutions for Resolving Direct Local AAR Dependency Errors in Android Gradle Plugin 4.0.0

Problem Background and Error Analysis

With the upgrade to Android Gradle Plugin (AGP) 4.0.0-beta03, many developers encountered a critical error when building Android library modules: Direct local .aar file dependencies are not supported when building an AAR. This error message explicitly states that direct dependencies on local AAR files are not supported when building AAR files. The message further explains that the resulting AAR would be "broken" because classes and Android resources from any local AAR file dependencies would not be packaged into the final AAR.

In reality, this limitation existed in earlier versions of AGP, but those versions didn't throw this explicit error—instead, they silently generated incomplete AAR files. This means that even with older AGP versions, if a library module directly depended on local AAR files, the generated AAR was incomplete, requiring manual inclusion of these AAR dependencies in application projects using the library.

Technical Principles Deep Dive

To understand this limitation, it's essential to understand how the Android build system handles AAR dependencies. AAR (Android Archive) files contain not only compiled Java class files but also Android-specific resources, manifest files, and other metadata. When building an Android library module, the build system needs to "flatten" and merge all dependencies into the final AAR.

For direct dependencies on local AAR files, the build system cannot resolve and extract their contents during the build process. This is because AAR files are essentially compressed archives that need to be unpacked, processed, and repackaged during the build. When a library module directly references a local AAR file, the build system cannot determine how to handle these "nested" AAR contents, so it chooses to throw an error rather than generate an incomplete build artifact.

In contrast, AAR dependencies from remote repositories (such as Maven Central or JCenter) work correctly because these dependencies are downloaded, resolved, and treated as external dependencies during the build. The build system knows how to fetch dependency metadata from remote repositories and reference them properly during the build process.

Solution One: Creating Standalone AAR Modules

This is the most recommended approach to solve this problem, applicable to all versions of Android Studio and AGP. The core idea is to wrap the local AAR file into a standalone Gradle module and then reference it via project dependency.

Here are the detailed implementation steps:

1. Create Module Directory Structure: Create a new directory in the project root to store the AAR file and corresponding build configuration. For example, if the AAR file is named mylibrary.aar, create a directory like mylibrary-module.
2. Configure Build Script: In the newly created directory, create a build.gradle file and add the following configuration:

configurations.maybeCreate("default")
artifacts.add("default", file('mylibrary.aar'))

This code creates a configuration named "default" and adds the AAR file as an artifact for this configuration. This way, when other modules depend on this module, Gradle knows how to provide the AAR file.

include ':mylibrary-module'

dependencies {
    implementation project(':mylibrary-module', configuration = "default")
}

By wrapping the local AAR file into a complete Gradle module, the build system can correctly identify and process it, avoiding the issues with direct local AAR dependencies.

Solution Two: Using compileOnly Dependencies

As an alternative approach, consider using the compileOnly configuration to declare AAR dependencies. This method is suitable for scenarios where the AAR is only needed during compilation and doesn't need to be packaged into the final AAR.

In the library module's build.gradle file, configure it as follows:

dependencies {
    compileOnly files('libs/mylibrary.aar')
}

The advantage of using the compileOnly configuration is its simplicity—no additional modules need to be created. However, this approach has an important limitation: application projects using this library must manually include the same AAR dependency. This means that if a library module uses an AAR dependency declared with compileOnly, all application projects using that library need to explicitly add this AAR dependency in their own build.gradle files.

This method is suitable for the following scenarios:

• The AAR dependency is optional functionality, not a core part of the library
• Library users are already aware that they need to manually add this dependency
• The AAR dependency might have multiple versions depending on usage scenarios

Solution Three: Publishing to Remote Repositories

From an architectural design perspective, the ideal solution is to publish the AAR file to a remote repository (such as Maven Central, JCenter, or a private Maven repository). This way, library modules can reference it through standard dependency declarations:

dependencies {
    implementation 'com.example:mylibrary:1.0.0@aar'
}

Publishing AARs to remote repositories offers several advantages:

• More standardized dependency management, aligning with modern build system best practices
• Support for version control and dependency resolution
• Facilitates team collaboration and continuous integration
• Avoids issues with local file path dependencies

Although setting up remote repositories requires some initial work, it's a worthwhile investment for long-term project maintenance. Especially for team projects or open-source libraries, using remote repositories can significantly simplify dependency management.

Version Compatibility Considerations

It's worth noting that different versions of Android Studio handle AAR imports differently. In versions before Android Studio 4.0.0, AAR files could be imported via the graphical interface: File → New → New Module → Import .JAR/.AAR Package. This method automatically created the corresponding module configuration.

However, in Android Studio 4.0.0 and later versions, this option has been removed. Therefore, the manual module creation method has become the only option. This change reflects the Android build system's evolution toward more explicit and controllable configuration approaches, requiring developers to have a deeper understanding of the build process.

Best Practice Recommendations

Based on the above analysis, we propose the following best practice recommendations:

1. Prioritize Standalone Module Solution: For most projects, creating standalone AAR modules is the most stable and maintainable solution. This approach aligns with AGP's design philosophy, ensuring predictable builds.
2. Consider Long-Term Architecture: If a project requires long-term maintenance, or if the AAR dependency will be used by multiple projects, consider publishing it to a remote repository. Although this requires more upfront work, it offers better maintainability and scalability.
3. Define Dependency Scope Clearly: Carefully consider the scope of each dependency. If an AAR is only needed during compilation, consider using compileOnly. However, be aware that this places additional burden on library users.
4. Keep Build Configuration Clean: Regardless of the chosen solution, maintain clear and concise build configurations. Avoid duplicating the same dependencies in multiple places, ensuring that build scripts are easy to understand and maintain.

Conclusion

The "Direct local .aar file dependencies are not supported" error introduced in Android Gradle Plugin 4.0.0 actually makes explicit a latent issue that existed in previous versions. This limitation ensures the completeness and consistency of build artifacts, preventing the generation of incomplete AAR files.

By creating standalone AAR modules, using compileOnly dependencies, or publishing AARs to remote repositories, developers can effectively resolve this issue. Each solution has its applicable scenarios, advantages, and disadvantages, and developers should choose the most appropriate approach based on their project's specific requirements and constraints.

Understanding the technical principles behind this error not only helps solve the current problem but also enables developers to better understand how the Android build system works, laying a solid foundation for future project development.