Gradle Plugin (Android)
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()
}
}
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.
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 {
buildType.set("release") // Optional, defaults to 'release'
}
performance {
projectPath.set(":perf") // Required for performance testing
buildType.set("release") // Optional, defaults to 'release'
}
snapshots {
buildType.set("snapshots") // Optional, snapshots use debug builds, we recommend using separate build type.
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
}
}
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
Field | Type | Default | Description |
---|---|---|---|
sha | String | HEAD branch commit sha | The Git sha of the HEAD build. |
baseSha | String | base branch commit sha | The Git sha of the base build to compare against. |
branchName | String | Current branch name | The name of the branch being built. |
prNumber | String | The number of the pull request being built. | |
gitHub.repoOwner | String | Repo ID before '/' | The owner of the GitHub repository. |
gitHub.repoName | String | Repo ID after '/' | The name of the GitHub repository. |
gitLab.projectId | String | The 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 {
buildType.set("release") // Optional, Build type to use for grouping builds in the Emerge dashboard
}
}
Properties
Field | Type | Default | Description |
---|---|---|---|
buildType | String | release | The build type to use for grouping builds in the Emerge dashboard. |
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 {
buildType.set("release") // Optional, Build type to use for grouping builds in the Emerge dashboard
perfProjectPath.set(":perf") // Required, Module path to the Emerge performance module
}
}
Properties
Field | Type | Default | Description |
---|---|---|---|
perfProjectPath | String | The module path to the Emerge performance module. | |
buildType | String | release | The build type to use for grouping builds in the Emerge dashboard. |
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`
buildType.set("snapshots") // Optional, build type to use for grouping builds in the Emerge dashboard
}
}
Properties
Field | Type | Default | Description |
---|---|---|---|
snapshotsStorageDirectory | String | /build/emerge/snapshots/outputs | Path to local snapshot image storage |
includeFromMainSourceSet | Boolean | false | Enables composable previews snapshots from the main sourceSet |
buildType | String | release | The build type to use for grouping builds in the Emerge dashboard. |
Configuration cache support
The 2.0 release of the Emerge gradle plugin supports the Gradle configuration cache.
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
Task | Description |
---|---|
emergeUpload{Variant}Apk | Upload an APK matching the specified variant to Emerge for size analysis. |
emergeUpload{Variant}Aab | Upload an AAB matching the specified variant to Emerge for size analysis. |
Performance
Task | Description |
---|---|
emergeGeneratePerformanceProject | Create a pre-configured Emerge performance module. Only available if perfProjectPath value is set and doesn't yet exist . |
emergeUpload{Variant}PerfBundle | Upload an AAB matching the specified variant to Emerge packaged with the perfProjectPath 's test APK. |
emergeLocal{Variant}Test | Run 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
Snapshots
Task | Description |
---|---|
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. |
Migration from 1.X
There are a number of significant changes & improvements from 1.X to 2.0. See below for details on breaking changes.
General
- Root-project configuration is no longer supported. Users should move the Emerge plugin's
configuration to the application module(s) they wish to use with Emerge. - Top-level
buildType
field has been removed in favor of per-productbuildType
setting- We recommend setting any existing
buildType
values assize.buildType
.
- We recommend setting any existing
- Top-level
performanceProjectPath
has been moved toperformance.projectPath
.
VCS
vcsOptions
has becomevcs
.vcsOptions.gitHubOptions
has becomevcs.gitHub
.vcsOptions.gitLabOptions
has becomevcs.gitLab
.
Performance
- Users must now add the
kotlin-android
plugin to their performance module:
plugins {
id("org.jetbrains.kotlin.android")
}
- Users must now add the Emerge perf test SDK dependency to their performance module:
// ...
dependencies {
implementation("com.emergetools.test:performance:<latest_version>")
}
Launch booster
- Removal of
launchBooster
extension. - Removal of
emergeGenerate{Variant}BaselineProfile
task.
Updated 20 days ago