Gradle Tasks & Configuration

Current latest version: 1.6.0 (last updated May 10, 2023)

Supported AGP & Gradle versions

Emerge officially supports AGP versions 7.0+ and 8.0+ and Gradle versions 7+ and 8+.

As of May 10, 2023, Emerge does not officially support Gradle's configuration caching features, but we are actively exploring support for this in the near future.

Tasks

General

emergeUpload<Variant><Aab|Apk> Task

Added in version 1.0.0.

Builds and uploads an APK or AAB for size and/or performance analysis. For example:

./gradlew emergeUploadReleaseAab

Using a release variant is recommended, but any variant defined for your application is supported. AAB is recommended but APK is supported as well.

Configuring upload for Continuous Integration (CI)

A few extra arguments are necessary for pull request diffs (comments & status checks) to work. Emerge will try to set these automatically if using Git.

• In the vcsOptions block:
  • sha: SHA hash of the commit that the app was built from.
  • baseSha: SHA hash of the base commit the app was built from. For example, the last commit from main before the current branch was created.
  • branchName: Name of the current git branch.
  • prNumber: Number of the pull request that triggered this build.
  • gitHubOptions block:
    • repoOwner: Name of the GitHub repository owner. Usually an organization.
    • repoName: Name of the GitHub repository.

Optionally, include the following for additional information:

• buildType: A string indicating what type of build this is. "release" by default if not specified. For example, this could be something like "alpha", "beta" or anything of your choosing depending on the type of build that's being uploaded.

These parameters work with the Emerge GitHub app to find the base build that was already uploaded and associate the analysis results with the right pull request. Here's an example:

plugins {
    // …
    id("com.emergetools.android") version "1.4.1"
}

// …

emerge {
    appProjectPath.set(":app") // The primary subproject for your app.
  
    apiToken.set(System.getenv("EMERGE_API_TOKEN"))

    vcsOptions {
        sha.set("sha")
        baseSha.set("baseSha")
        branchName.set("branchName")
        prNumber.set("prNumber")
          
        gitHubOptions {
            repoOwner.set("YourOrg")
            repoName.set("RepoName")
        }
    }
  
    buildType.set("release") // Optional, customize this based on the build you're uploading.
}

plugins {
    // …
    id "com.emergetools.android" version "1.2.0"
}

// …

emerge {
    appProjectPath = ":app" // The primary subproject for your app.
  
    apiToken = System.getenv("EMERGE_API_TOKEN")

    vcsOptions {
        sha = "sha"
        baseSha = "baseSha"
        branchName = "branchName"
        prNumber = "prNumber"
          
        gitHubOptions {
            repoOwner = "YourOrg"
            repoName = "RepoName"
        }
    }
  
    buildType = "release" // Optional, customize this based on the build you're uploading.
}

Performance Testing

emergeUpload<Variant>PerfBundle Task

Added in version 1.5.0.

Builds and uploads an AAB from the specified appProjectPath and a test APK from the performanceProjectPath. Meant to be used for custom UI tests to be used with Custom Flow Performance Analysis (Android).

For example, if the following config is set:

...

emerge {
    appProjectPath.set(":app")
    performanceProjectPath.set(":performance")
}

...

emerge {
    appProjectPath = ":app"
    performanceProjectPath = ":performance"
}

And if the following command is executed:

./gradlew emergeUploadReleasePerfBundle

This will build the release variant AAB from the :app module, and the matching release variant from the :performancemodule, then upload both to Emerge.

Emerge will automatically run all @EmergeTest annotated performance tests from the head build's test APK when running a comparison. For more details on Emerge's custom UI performance tests, see Custom Flow Performance Analysis (Android).

emergeGeneratePerformanceProject Task

Added in version 1.1.0.

Generates a performance testing subproject. This is only necessary for custom performance tests.

First make sure to configure the name of the new project by setting the performanceProjectPath in the top-level build.gradle(.kts) file:

emerge {
    // …
  
    performanceProjectPath.set(":performance")
}

emerge {
    // …
  
    performanceProjectPath = ":performance"
}

At this point the project shouldn't exist yet, but the following command will generate it:

./gradlew emergeGeneratePerformanceProject --package com.myapp.performance

For more on custom performance tests see Custom Flow Performance Analysis (Android).

emergeLocalTest Task

Added in version 1.1.0.

Builds, installs and runs Emerge performance tests on a local device. Meant for debugging, does not provide actual performance results.

Your tests must be placed in a performance testing subproject. The subproject path must be configured like so:

emerge {
    // …
  
    performanceProjectPath.set(":performance")
}

emerge {
    // …
  
    performanceProjectPath = ":performance"
}

A device or emulator must be available. Then, to run the tests locally:

./gradlew emergeLocalReleaseTest

Any variant defined for your application is supported. The output will let you know whether tests ran successfully or if certain issues need to be addressed. We recommend making sure tests can run locally before uploading them to Emerge.

For more on custom performance tests see Custom Flow Performance Analysis (Android).

Launch Booster (Baseline Profiles)

emergeGenerate<Variant>BaselineProfile Task

Added in version 1.1.0.

Generates a Baseline Profile using Emerge's Launch Booster service. For example:

./gradlew emergeGenerateReleaseBaselineProfile

Only non-debuggable variants are supported.

For more on baseline profiles see Baseline Profiles (Android).

[Deprecated]Disabling Launch Booster

Deprecated in version 1.6.0. Added in version 1.3.0.

As of 1.6.0, the Emerge gradle plugin no longer creates a custom variant for generating baseline profiles. Disabling the task to avoid the creation of these variants is no longer necessary. The notes below only apply to versions <1.6.0.

Launch booster automatically creates custom variants for all non-debuggable variants of your app, allowing Emerge to configure the proper proguard/build settings on your behalf with no work or maintenance on your part.

If you wish to not have these variants generated automatically, you can disable Launch Booster with a Gradle property:

emerge {
  ...

  launchBooster {
    enabled.set(false)
  }
}

emerge {
  ...
  
  launchBooster {
    enabled = false
  }
}