Gradle Plugin (Android)

Suggest Edits

The Emerge Gradle plugin is the recommended way to integrate with Emerge on Android. Its main features are:

  • Uploading builds to Emerge for size analysis, performance analysis & snapshot testing.
  • Creating and maintaining a performance subproject for custom performance analysis.
  • Debugging & running performance and snapshot tests locally

Quick setup

Add the Gradle plugin portal to your plugin repositories

The Emerge Gradle plugin is hosted by the Gradle plugin portal. In new projects it should already be part of the plugin repositories. If not, you'll need to add it in settings.gradle(.kts):

pluginManagement {
  repositories {
    gradlePluginPortal()
  }
}

Add the Gradle plugin dependency

Add the gradle plugin dependency to your lib.versions.toml plugin dependency definitions.

[versions]
emergeGradlePlugin = "<latest_version>"

[plugins]
emerge = { id = "com.emergetools.android", version.ref = "emergeGradlePlugin"}

Latest gradle plugn version: Gradle Plugin Portal Version

Apply the Emerge Gradle plugin to your top-level project

In your application module's build.gradle(.kts):

plugins {
  id("com.emergetools.android")
}

emerge {
  // Emerge uses the EMERGE_API_TOKEN env variable by default, so no need to set env explicitly
  apiToken.set(System.getenv("EMERGE_API_TOKEN"))
}

apiToken is required. Other configuration properties are documented below in Configuration

See the emerge-android repo for the latest version.

Obtain an API key

Follow our guide on obtaining an API key.

We recommend storing this token in a secrets store, an environment variable, or a Gradle property file. The example in this guide uses the EMERGE_API_TOKEN environment variable, which the Emerge plugin will pick up and set as the default value. for apiToken.

👍

All done!

You're ready to start using the Emerge Gradle plugin. Read on for some commonly used tasks.

Tasks

Emerge offers numerous tasks to help facilitate common use cases. We recommend running these in CI to get the full functionality Emerge offers.

Size

TaskDescription
emergeUpload{Variant}ApkUpload an APK matching the specified variant to Emerge for size analysis.
emergeUpload{Variant}AabUpload an AAB matching the specified variant to Emerge for size analysis.

Snapshots

TaskDescription
emergeLocalSnapshots{Variant}Run snapshot tests locally.
emergeUploadSnapshotBundle{Variant}Builds & uploads target & test APKs for the specified variant. Snapshots will be generated & saved in Emerge's cloud snapshot offering.

Performance

TaskDescription
emergeGeneratePerformanceProjectCreate a pre-configured Emerge performance module. Only available if perfProjectPath value is set and doesn't yet exist .
emergeUpload{Variant}PerfBundleUpload an AAB matching the specified variant to Emerge packaged with the perfProjectPath's test APK.
emergeLocal{Variant}TestRun performance tests from perfProjectPath locally for debugging & testing.

Note: If wanting to run size & custom performance tests for an upload, you can just use the emergeUpload{variant}PerfBundle task. We'll automatically run size analysis for the release build as well 😄

Configuration

The Emerge Gradle plugin is designed to be configured in the application-level build.gradle(.kts) file of your project.

Depending on your configuration, in your project's root build.gradle(.kts) file, you might need to include the Emerge gradle plugin, but not apply it, to ensure the plugin is available in your project's classpath:

// root-level build.gradle.kts
plugins {
  // ..
  id("com.emergetools.android") version "<latest_version>" apply false
}

Full configuration

// app-module build.gradle.kts
plugins {
  id("com.emergetools.android")
}

emerge {
  // Emerge uses the EMERGE_API_TOKEN env variable by default, so no need to set env explicitly
  apiToken.set(System.getenv("EMERGE_API_TOKEN"))

  vcs {
    sha.set("...") // Optional, will be set automatically using Git information.
    baseSha.set("...") // Optional, will be set automatically using Git information.
    branchName.set("my-feature") // Optional, will be set automatically using Git information.
    prNumber.set("123")

    gitHub {
      repoOwner.set("...") // Required for CI status checks (only if using GitHub)
      repoName.set("...") // Required for CI status checks (only if using GitHub)
    }

    gitLab {
      projectId.set("...") // Required for CI status checks (only if using GitLab)
    }
  }

  size {
    tag.set("release") // Optional, defaults to 'release'
    // Alternatively, use `setFromVariant()` to set the tag from the Android build variant
    tag.setFromVariant()
    enabled.set(true) // Optional, defaults to true.
  }

  performance {
    projectPath.set(":perf") // Required for performance testing
    tag.set("release") // Optional, defaults to 'release'
    // Alternatively, use `setFromVariant()` to set the tag from the Android build variant
    tag.setFromVariant()
    enabled.set(true) // Optional, defaults to true.
  }

  snapshots {
    includeFromMainSourceSet.set(true) // Optional, enables composable previews snapshots from the main sourceSet, defaults to `false`
    snapshotsStorageDirectory.set("/src/main/snapshots") // Storage of locally generated snapshots
    tag.set("snapshots") // Optional, snapshots use debug builds, we recommend using separate tag.
    // Alternatively, use `setFromVariant()` to set the tag from the Android build variant
    tag.setFromVariant()
    enabled.set(true) // Optional, defaults to true.
  }
  
  reaper {
    publishableApiKey.set("<Reaper API key>") // The key used to identify Reaper reports for your organization.
    tag.set("release")  // Optional, defaults to 'release'
    // Alternatively, use `setFromVariant()` to set the tag from the Android build variant name
    tag.setFromVariant()
    enabled.set(true) // Optional, defaults to false
  }
}

VCS

Emerge is best designed to work as part of your CI workflow for diffing and comparing a build's size,
performance and snapshots.

To ensure these comparisons are accurate, Emerge leverages VCS information to accurately determine the proper comparison builds.

By default, necessary Git values are set automatically for you. If you need to override these
values, you can do so using the vcs extension.

emerge {
  vcs {
    sha.set("...") // Optional, will be set automatically using Git information.
    baseSha.set("...") // Optional, will be set automatically using Git information.
    branchName.set("my-feature") // Optional, will be set automatically using Git information.
    prNumber.set("123") // Required for PR status checks & comments, not set automatically.
  }
}
Properties
FieldTypeDefaultDescription
shaStringHEAD branch commit shaThe Git sha of the HEAD build.
baseShaStringbase branch commit shaThe Git sha of the base build to compare against.
branchNameStringCurrent branch nameThe name of the branch being built.
prNumberStringThe number of the pull request being built.
gitHub.repoOwnerStringRepo ID before '/'The owner of the GitHub repository.
gitHub.repoNameStringRepo ID after '/'The name of the GitHub repository.
gitLab.projectIdStringThe ID of the GitLab repository.

GitHub

The GitHub sub-extension can be used to set GitHub-specific values. These are set automatically
using repoId information from git's remoteUrl if not specified.

These are used for CI integrations, like posting GitHub comments and status checks.

emerge {
  vcs {
    ..

    gitHub {
      repoOwner.set("...") // Required for CI status checks (only if using GitHub)
      repoName.set("...") // Required for CI status checks (only if using GitHub)
    }
  }
}

GitLab

The GitLab sub-extension can be used to set GitLab-specific values. Unlike GitHub values, these
are not set automatically and will need to be set manually for GitLab CI integration.

emerge {
  vcs {
    ..

    gitLab {
      projectId.set("...") // Required for CI status checks (only if using GitLab)
    }
  }
}

Size

The size extension allows you to configure size-specific properties.

emerge {
  ...

  size {
    tag.set("release") // Optional, tag to use for grouping builds in the Emerge dashboard
    // Alternatively, use `setFromVariant()` to set the tag from the Android build variant
    tag.setFromVariant()
  }
}
Properties
FieldTypeDefaultDescription
tagStringreleaseThe tag to use for grouping builds in the Emerge dashboard.
enabledBooleantrueIf size tasks/project configuration are enabled.

Performance

By default, Emerge will automatically add the necessary build configuration needed for the
specified perfProjectPath module.

Additionally, the performance extension allows you to configure perf-specific properties.

emerge {
  ...

  performance {
    perfProjectPath.set(":perf") // Required, Module path to the Emerge performance module
    tag.set("release") // Optional, tag to use for grouping builds in the Emerge dashboard
    // Alternatively, use `setFromVariant()` to set the tag from the Android build variant
    tag.setFromVariant()
  }
}
Properties
FieldTypeDefaultDescription
perfProjectPathStringThe module path to the Emerge performance module.
tagStringreleaseThe tag to use for grouping builds in the Emerge dashboard.
enabledBooleantrueIf performance tasks/project configuration are enabled.

Snapshots

The snapshot extension allows you to configure snapshot-specific properties.

emerge {
  ...

  snapshots {
    snapshotsStorageDirectory.set("/src/main/snapshots") // Optional, path to local snapshot image storage, defaults to `/build/emerge/snapshots/outputs`
    includeFromMainSourceSet.set(true) // Optional, enables composable previews snapshots from the main sourceSet, defaults to `false`
    tag.set("snapshots") // Optional, tag to use for grouping builds in the Emerge dashboard
    // Alternatively, use `setFromVariant()` to set the tag from the Android build variant
    tag.setFromVariant()
  }
}
Properties
FieldTypeDefaultDescription
snapshotsStorageDirectoryString/build/emerge/snapshots/outputsPath to local snapshot image storage
includeFromMainSourceSetBooleanfalseEnables composable previews snapshots from the main sourceSet
tagStringreleaseThe tag to use for grouping builds in the Emerge dashboard.
enabledBooleantrueIf snapshot tasks/project configuration are enabled.

Reaper

The reaper extension allows you to configure Reaper - an SDK for dead code removal at scale.

emerge {
  ...

  reaper {
    publishableApiKey.set("<Reaper API key>") // The key used to identify Reaper reports for your organization.
    tag.set("release")  // Optional, defaults to 'release'
    // Alternatively, use `setFromVariant()` to set the tag from the Android build variant name
    tag.setFromVariant()
    enabled.set(true) // Optional, defaults to false
  }
}
Properties
FieldTypeDefaultDescription
publishableApiKeyStringThis key is used to identify Reaper reports sent from your application for your organization. It is safe to include in client-side code. The key can be found at here.
tagStringreleaseThe tag to use for grouping builds in the Emerge dashboard.
enabledBooleanfalseInstruments compiled bytecode to support Reaper and auto-initializes Reaper at runtime.

Configuration cache support

The 2.0 release of the Emerge gradle plugin supports the Gradle configuration cache.

Updated 8 days ago