Android: no first-class way to bundle a local AAR / declare an extra Gradle repository

[ggiesen]

Summary

Briefcase's Android (Gradle) backend can declare remote Maven dependencies
(build_gradle_dependencies), but there is no first-class, documented way to:

1. declare an extra/local Gradle repository (e.g. flatDir, mavenLocal, or a
   custom maven { url … }), or
2. bundle and link a local artifact — a local .aar, a local .jar, or a local
   Maven artifact built outside the app.

build_gradle_dependencies entries resolve only against the repositories hard-coded
in the generated build.gradle (google(), mavenCentral()), and there's no config
key to add another. The app build.gradle has implementation fileTree(dir: 'libs', include: ['*.jar']), but that globs *.jar only (not *.aar), and there's no
documented way to stage files into app/libs (the build/ tree is regenerated on
create/update).

The only current workaround is build_gradle_extra_content (raw text appended to
app/build.gradle) plus manually getting the artifact onto disk where a hand-written
flatDir repo can find it — i.e. exactly the escape hatch, not a first-class feature.

Use case

I maintain an app whose alarm engine is a small Kotlin module shipped as a prebuilt
Android AAR (it needs AlarmManager/foreground-service/boot-receiver behavior that
isn't practical in pure Python). To get it into the Briefcase build today I have to:

build_gradle_extra_content = """
repositories { flatDir { dirs "${rootProject.projectDir}/../../../../native/<module>/build/outputs/aar" } }
"""
build_gradle_dependencies = [
    # …androidx deps…
    ":<module>-release@aar",   # positional flatDir match by filename
]

This works but is fragile: the flatDir repo is injected via raw text, the dependency
is matched positionally by filename, and the relative path has to walk out of the
regenerated build tree. A first-class mechanism would make "bundle a local native
module" a supported, documented story.

Proposal (seeking direction before a PR)

Smallest-first, Android-first: add a repository-declaration capability — e.g. a
build_gradle_repositories key (mirroring build_gradle_dependencies) that the
template renders into the Gradle repositories {} block — since the hard-coded
google()/mavenCentral() set is the actual blocker. Combined with the existing
build_gradle_dependencies, that's enough to reference a local flatDir/mavenLocal
artifact cleanly.

A fuller option is a per-platform native_libraries/local_libraries table that
stages a project-relative artifact into the build (on every create/update, since
build/ is regenerated) and wires it into dependencies — but that's more design
surface, so I'd rather confirm the approach first. Note the fileTree glob is
*.jar-only, so AAR support needs either a flatDir repo or implementation files('libs/foo.aar').

Prior art / related

• Add ability for libraries to declare build-time requirements #485 — Add ability for libraries to declare build-time requirements (open; the
  foundational issue; explicitly cites Android Jetpack libs + an iOS CocoaPod). A
  local-artifact/repository feature should align with this.
• Allow Android apps to specify their own list of libraries #1610 — the merged PR that added build_gradle_dependencies (precedent that a
  narrow, general key is welcome rather than only the generic escape hatch).
• Allow third-party packages to supplement Briefcase configuration #1879 — Allow third-party packages to supplement Briefcase configuration (open;
  same problem space, an alternative “auto-derive config” axis).
• Allow configuration of custom build params for macos Xcode builds in pyproject.toml #1861 — custom build params for macOS Xcode builds (open; the iOS/macOS side has
  no build_gradle_extra_content-equivalent today, so a local XCFramework is a
  separate, larger lift — out of scope here).

Questions

1. Is a build_gradle_repositories key (or an equivalent first-class
   local-artifact/repository mechanism) something you'd accept, and is the
   build_gradle_* family the right place — or do you prefer the Add ability for libraries to declare build-time requirements #485 “package
   declares its own native requirements” model / Allow third-party packages to supplement Briefcase configuration #1879’s auto-derive approach?
2. For local AAR specifically: would you prefer teaching the template to emit
   files('libs/*.aar') / broaden the fileTree glob, or a declared flatDir repo?

Happy to implement once there's a preferred direction (Android-first; iOS XCFramework
as a later, separate effort).

[freakboy3742]

#485 describes a slightly different use case - that's about third-party Python packages that have binary system requirements.

#1879 is also a feature of third party packages - describing that some third party packages may need to influence how a Briefcase app is packaged. This is a particular issue for iOS and Android projects because they may need to influence how the package is bundled. The examples given there are bleekware and toga - third party packages on PyPI that can be packaged for Android; but if they are included, there requirement modules to be added to the Briefcase app.

#1861 is macOS specific, and has more to do with configuring the build (e.g., tweaking a compiler flag). #2180 is the better analog in the macOS space - requesting the ability to include a third-party binary framework that could be accessed at runtime.

#1610 is the most direct analog to what you're requesting - a specific expansion point for one specific type of dependency. To that end, and approach like build_gradle_repositories would make sense - adding the ability to include a specific third-party repository to the list that are in the template by default, augmenting the default list of google() and mavenCentral().

That then leaves the additional problem of adding arbitrary files to a project. This is mentioned in the discussion on #2180 as one possible approach; "copy these arbitrary files into these locations" - something like:

[tool.briefcase.app.my-app.android.additional_files]
"app/src/main" = ["path/to/android/content", "path/to/other/content"]
"app/src/main/res/drawable/other.xml" = "path/to/other/drawable.xml"

In the my-app Android project, this would copy the entire subtrees of path/to/android/content and path/to/other/content into the app/src/main folder, and the path/to/other/drawable.xml file as app/src/main/res/drawable/other.xml. I'd guess these would be treated as "resources", so --update-resources would perform another copy, overlaying the existing files. We'd need to clarify whether the specified source paths are copied into the target, and what conditions would lead to a directory being created (i.e., would the main folder contain a content folder in this specification, or are content and main considered equivalent?).

It seems like that, combined with adding *.aar as a standard file tree inclusion (if that's a common distribution format for Android), would meet your requirements.