Build Microbenchmarks without Gradle

This page describes configuring a non-Gradle build system when using the Microbenchmark library.

Although the Microbenchmark library ships a Gradle plugin to integrate directly with the Android Gradle plugin, you can also use it in other build systems, such as Bazel or Buck.

Instrumentation

Use AndroidBenchmarkRunner or a subclass as your instrumentation runner by specifying it in the instrumentation block of the test manifest:

<manifest
    package="com.example.library.test" ...>

    <instrumentation android:name="androidx.benchmark.junit4.AndroidBenchmarkRunner" />
    ...
</manifest>

To get accurate measurements, benchmarks must not be debuggable. If you don't set the debuggable flag correctly, the library throws an error, rather than reporting invalid results. You might need to toggle this setting during local runs for use with Android Studio profilers, which require debuggable=true.

You can build Microbenchmarks to run in two ways: within a self-instrumenting APK, or with one test APK instrumenting another APK.

Self-instrumenting APKs

With a self-instrumenting APK—as output by Gradle for an androidTest directory from com.android.library—you must disable debuggable in the single APK's Android manifest:

<manifest
    package="com.example.library.test" ...>

    <instrumentation
        android:name="androidx.benchmark.junit4.AndroidBenchmarkRunner"
        android:targetPackage="com.example.library.test"/>

    <application android:debuggable="false"/>
</manifest>

App APK instrumented by test APK

If your build outputs two APKs—an app APK and test APK, as output by Gradle for the androidTest directory from the com.android.app package—you must set the app APK to debuggable=false. The test APK's debuggable flag is ignored by the Android OS.

<!-- Test manifest. -->
<manifest
    package="com.example.android.app.test" ...>

    <instrumentation
        android:name="androidx.benchmark.junit4.AndroidBenchmarkRunner"
        android:targetPackage="com.example.android.app"/>
    <!-- This debuggable is ignored by the OS. -->
</manifest>

<!-- App being tested. -->
<manifest
    package="com.example.android.app" ...>

    <application android:debuggable="false"/>
</manifest>

Android Studio and Gradle don't support microbenchmarking an app module APK. This is due to the complexity of supporting an additional testing directory that depends on a non-debuggable, optimized, or minified variant of the APK, but without minification breaking calls from benchmarks into app code.

Compilation

We recommend compiling your microbenchmark APK before running tests, using the following command:

adb shell cmd package compile -f -m speed com.example.benchmark

Minification and optimization

We recommend using minification and optimization for your benchmarks to get performance that is close to release. For example code, see the Benchmark sample project.

Code coverage

We recommend running benchmarks with coverage disabled and without any library or DEX mangling by tools such as JaCoCo.

For this reason, we recommend you isolate benchmarks as a source set from other instrumentation tests and build them separately with release dependencies. This avoids having to build tests more than once, both with and without coverage.

Debug variants of libraries that your benchmark depends on, especially those built locally, might be built with coverage enabled.

Run your tests

You can run your tests from the command line and specify the classes to run with, as shown in the following example:

adb shell am instrument -w com.example.benchmark/androidx.benchmark.junit4.AndroidBenchmarkRunner

To configure the Microbenchmark library at runtime without Gradle, see Microbenchmark instrumentation arguments.

Previous
Microbenchmark and Hilt