Library Authors: You Can't Always Get What You Want

Given the rise of Android Studio, more and more Android library authors are creating Android library projects and publishing them as AARs, as opposed to trying to stick to plain JARs. Nowadays, this approach as the added benefit offering manifest merging, so a library author can contribute elements to the manifest:

• <uses-permission> and <uses-feature> elements that the library needs for various operations

• components (e.g., <activity>) elements, to save the developer using the library to have to manually add them

• a <uses-sdk> element, with the library author’s own take on what the minSdkVersion and targetSdkVersion should be

• and so on

Library authors should not get complacent, though, and assume that just because they ask for it in the library’s manifest, that they will get it. Developers have the ability to reject anything introduced by the library’s manifest, through two major approaches:

1. Add tools:node="remove" attributes to copies of elements to be blocked, such as having tools:node="remove" on a <uses-permission> element to specifically block libraries from adding that permission requirement

2. Add tools:overrideLibrary to the <uses-sdk> element, indicating libraries whose opinions on minSdkVersion and targetSdkVersion should be ignored

Library authors need to practice defensive programming and make sure that they react to the environment around them.

If you gotta gotta gotta have some permission, make sure that your library “fails fast”, so that the developer is guaranteed to find out that blocking the permission is not supported. This may come about naturally by use of your library, such as a camera library failing quickly when trying to use android.hardware.Camera if the CAMERA permission were blocked. However, if the permission is essential but may not be used until later in the workflow, use PackageManager to determine if you have the permission, and fail early on with your own exception, rather than wait.

If the permission is not essential for the overall library, but it is essential for some feature of the library, try to gracefully degrade if the feature is used but the permission is blocked. For example, some app developers try to avoid WRITE_EXTERNAL_STORAGE for fear of backlash from users. If your app would default to using external storage for something (and therefore perhaps needs this permission), see if there is a workaround (e.g., have the file on internal storage and use FileProvider to serve it to third-party apps). Or, simply fail the request, ideally in some way that allows the user to understand what is going on or for the app developer to react to the missing feature. So, if you need WRITE_EXTERNAL_STORAGE and do not have it, through some custom checked exception, or have a canUseXXXFeature() method that the app developer should call to determine if the feature can be used, or something.

The same holds true for anything else that you introduce in the manifest:

• If you specify a minSdkVersion, recognize that your vote may be ignored, so you may be running on an older device. Where possible, try to handle that gracefully (e.g., use Build.VERSION.SDK_INT to see what you really are running on and react). Or, check the version information up front and fail fast, or at least introduce a warning to alert the developer that you’re not responsible for any VerifyError crashes due to your running on an older-than-expected Android device.

• If you specify a targetSdkVersion, you should be able to find out what the actual targetSdkVersion is from the ApplicationInfo object that you can get from PackageManager.

• If you added components and planned on trying to use those components yourself (e.g., register a PendingIntent pointing to a BroadcastReceiver that you had set up in your manifest), you can use PackageManager to determine if you actually have that BroadcastReceiver registered in the manifest.

• And so on.

Of course, this is all a pain. I need to do a better job of this myself for my CWAC libraries.

:: adds item to to-do list::

On the other hand, we really should have been doing this sort of thing before manifest merging came about, as we were expecting the app developer to manually set up these things in their app’s manifest… and they might not. Just because we can automate putting our requirements in the manifest does not eliminate our need to validate what we got and handle differences appropriately. As some old British guys have pointed out for years, you can’t always get what you want.