androidenv: documentation on aapt via `GRADLE_OPTS` is wrong/does not work

[Atemu]

This is the current documentation:

nixpkgs/doc/languages-frameworks/android.section.md

Lines 262 to 280 in 83e07f6

	If you are running the Android Gradle plugin, you need to export GRADLE_OPTS to override aapt2
	to point to the aapt2 binary in the Nix store as well, or use a FHS environment so the packaged
	aapt2 can run. If you don't want to use a FHS environment, something like this should work:
	```nix
	let
	buildToolsVersion = "30.0.3";
	# Use buildToolsVersion when you define androidComposition
	androidComposition = <...>;
	in
	pkgs.mkShell rec {
	ANDROID_HOME = "${androidComposition.androidsdk}/libexec/android-sdk";
	ANDROID_NDK_ROOT = "${ANDROID_HOME}/ndk-bundle";
	# Use the same buildToolsVersion here
	GRADLE_OPTS = "-Dorg.gradle.project.android.aapt2FromMavenOverride=${ANDROID_HOME}/build-tools/${buildToolsVersion}/aapt2";
	}
	```

However, when I try to run gradle with GRADLE_OPTS=-Dorg.gradle.project.android.aapt2FromMavenOverride=/nix/store/k8spr2mqms0xdbk1gc9ychx2avh66c7g-androidsdk/libexec/android-sdk/build-tools/35.0.0/aapt2, gradle still attempts to use the FHS-assuming binary it downloaded to the gradle cache which predictably fails:

> Could not resolve all files for configuration ':app:premiumDebugRuntimeClasspath'.
   > Failed to transform biometric-1.2.0-alpha05.aar (androidx.biometric:biometric:1.2.0-alpha05) to match attributes {artifactType=android-compiled-dependencies-resources, org.gradle.category=library, org.gradle.dependency.bundling=external, org.gradle.libraryelements=aar, org.gradle.status=release, org.gradle.usage=java-runtime}.
      > Execution failed for AarResourcesCompilerTransform: /Users/atemu/.gradle/caches/8.13/transforms/a203d07b82655c0b98705869af96ec4f/transformed/biometric-1.2.0-alpha05.
         > AAPT2 aapt2-8.9.1-12782657-linux Daemon #0: Daemon startup failed
           This should not happen under normal circumstances, please file an issue if it does.

--scan to get any sort of useful information out of gradle (why doesn't it just print the stderr of the failing command by default?!) confirms what it's doing:

            AAPT2 aapt2-8.9.1-12782657-linux Daemon #1: Unexpected error output: Could not start dynamically linked executable: /Users/atemu/.gradle/caches/8.13/transforms/d828a5b8de1e37f81feb90173f16523e/transformed/aapt2-8.9.1-12782657-linux/aapt2
            AAPT2 aapt2-8.9.1-12782657-linux Daemon #1: Unexpected error output: NixOS cannot run dynamically linked executables intended for generic
            AAPT2 aapt2-8.9.1-12782657-linux Daemon #1: Unexpected error output: linux environments out of the box. For more information, see:
            AAPT2 aapt2-8.9.1-12782657-linux Daemon #1: Unexpected error output: https://nix.dev/permalink/stub-ld

According to this, this env var apparently isn't about gradle cmd line opts at all and only concerns JVM options. This does not strike me as sane design in any way shape or form. There does not appear to be an environment variable documented which does what we want it to do.

I think we should instead solve this using a gradle wrapper (as in our own wrapping, not gradlew). Perhaps that would be a better design anyways given how easy it is to accidentally override env vars.

cc @numinit who authored this in 5b91d4a

[numinit]

Another way to do it is by putting the following in local.properties (yes... a file...) in the root of the project:

android.aapt2FromMavenOverride=/nix/store/k8spr2mqms0xdbk1gc9ychx2avh66c7g-androidsdk/libexec/android-sdk/build-tools/35.0.0/aapt2

This may be slightly more reliable. But, yes, GRADLE_OPTS is awful. I believe you have to restart the daemon for those options to take effect, which makes it work better in things like CI pipelines.

[Atemu]

GRADLE_OPTS does not work for me at all, even with a fresh daemon. As a workaround, it's easy enough to do gradle $GRADLE_OPTS ... but we should have a proper gradle that "just works" for android purposes.

Either that or our gradle should be (optionally) fhsenv'd so that it can run the downloaded aapt binaries (or whatever else there might be).

What do you think of the proposed solutions?

cc @NixOS/android btw.; didn't know that was a thing.

[numinit]

I always FHS wrap the builder in my Android sandboxes, and certainly think that approach is upstreamable. The "how to run bubblewrap in the sandbox and have it work in prod" hack is... well, sure something, and wild it works.

In my experience though, the AAPT2 override trick via GRADLE_OPTS works too... I'll check the exact details of how I managed to get it working over the next day. We use it in prod at $WORK both ways, so I'm pretty sure it works and I've dealt with both usecases before, including JARs that need a FHS in the sandbox to work properly.

[JohnRTitor]

FHS wrap the builder in my Android sandboxes

If we are talking about FHS wrapping android studio, it will make it harder to use the integrated terminal. For example, sudo won't work inside the container.

[numinit]

This would just be for a sandboxed builder, as in the derivation's builder attribute, as opposed to a shell. (I think @Atemu was talking about sandboxed Gradle execution, but I could be wrong).

If not, yeah, we'll likely need an Android wrapped gradle.

[Ralith]

I can confirm that GRADLE_OPTS as documented in the manual does not have any effect, even with cleared cache and a fresh daemon.

[Ralith]

Populating local.properties with android.aapt2FromMavenOverride=${ANDROID_HOME}/build-tools/${buildToolsVersion}/aapt2 was also not effective. Passing $GRADLE_OPTS populated per nixpkgs manual explicitly on the command line does work.

[spherinder]

For me it works to put android.aapt2FromMavenOverride=/nix/store/<hash>-android-sdk-env/share/android-sdk/build-tools/35.0.0/aapt2 into gradle.properties , but of course that misses the point of it being a setting local to the environment. Neither approach – GRADLE_OPTS nor local.properties – works for me.

[menixator]

I came across this issue as well. To get around it, I had to override the gradle package itself and added the property to /lib/gradle/gradle.properties.

The current gradle derivation(s) in nixpkgs unstable comes with a wrapper that for some reason does not allow you to override the actual gradle derivation that it is wrapping. I just ended up copying the entire gradle folder from nixpkgs to my flake and making the wrapper accept additional content to be added to the gradle.properties file that comes with the derivation.

I'd like to see the gradle wrapper reworked to allow more control of the gradle derivation that it is wrapping. Right now you can only override the arguments to the derivation. But overriding the attributes with overrideAttrs seems to be impossible while wrapping gradle.

The wrapFunction used to be exposed for 25.05 but its no longer there in unstable now. But honestly I'd rather do pkgs.gradle-wrapped.override { gradle = ... } than do something like pkgs.wrapGradle ... because the former is more idiomatic.

[numinit]

#449037 will be our attempt at fixing this long term. See also #72220.