README.md

# D8 dexer and R8 shrinker

The R8 repo contains two tools:

- D8 is a dexer that converts java byte code to dex code.
- R8 is a java program shrinking and minification tool that converts java byte
  code to optimized dex code.

## Obtaining prebuilts

There are several places to obtain a prebuilt version without building it
yourself.

### Google Maven (preferred)

Stable release versions and `-dev` versions are available from the Google Maven
repository. See https://maven.google.com/web/index.html#com.android.tools:r8.

Stable and `-dev` releases have been processed with R8. The corresponding
mapping file can be obtained through the following URL:

https://storage.googleapis.com/r8-releases/raw/<version>/r8lib.jar.map

### CI Archive

Our [CI](https://ci.chromium.org/p/r8/g/main/console) builds for each commit and
stores all build artifacts in Google Cloud Storage in the `r8-releases` bucket.

To obtain a prebuild from the CI for a specific stable or `-dev` version,
download it from the following URL:

    https://storage.googleapis.com/r8-releases/raw/<version>/r8lib.jar

To obtain a prebuild from the CI for a specific main branch hash, download it
from the following URL:

    https://storage.googleapis.com/r8-releases/raw/main/<hash>/r8lib.jar

The prebuilt JARs have been processed by R8, and for each build, the
corresponding mapping file is located together with the prebuild under the name
`r8lib.jar.map`.

To get prebuilds that have not been processed by R8, replace `r8lib.jar`
with `r8.jar` in the URLs above.

The Google Cloud Storage bucket `r8-releases` can also be used as a simple
Maven repository by using the following configuration for stable and `-dev`
versions:

    maven {
        url = uri("https://storage.googleapis.com/r8-releases/raw")
    }

and the following configuration for main branch builds:

    maven {
        url = uri("https://storage.googleapis.com/r8-releases/raw/main")
    }

See [Running D8](#running-d8) and [Running R8](#running-r8) below for
instructions on how to invoke D8 and R8 using the obtained `r8lib.jar` in
place of `build/libs/r8.jar`.

## Downloading source and building

The R8 project uses [`depot_tools`](https://www.chromium.org/developers/how-tos/install-depot-tools)
from the chromium project to manage dependencies. Install `depot_tools` and add it to
your path before proceeding.

The R8 project uses Java 8 language features and requires a Java 8 compiler
and runtime system.

Typical steps to download and build:


    $ git clone https://r8.googlesource.com/r8
    $ cd r8
    $ tools/gradle.py r8

The `tools/gradle.py` script will bootstrap using depot_tools to download
a version of gradle to use for building on the first run. This will produce
a jar file: `build/libs/r8.jar` which contains both R8 and D8.

## Setting up IntelliJ

Follow the instructions in the above section.

1. Open the root project `r8/` in IntelliJ
2. Navigate to "Settings" > "Build, Execution, Deployment" > "Build Tools" > "Gradle"
   1. Select `r8/third_party/gradle` as "Local installation" in "Distribution"
   2. Select `r8/third_party/openjdk/jdk-11/linux` as "Gradle JVM"
3. Sync the project using Gradle

In order to run tests it may currently be necessary to run `tools/test.py` from the command line first.

## <a name="running-d8"></a>Running D8

The D8 dexer has a simple command-line interface with only a few options.
D8 consumes class files and produce DEX.

The most important option is whether to build in debug or release mode.  Debug
is the default mode and includes debugging information in the resulting dex
files. Debugging information contains information about local variables used
when debugging dex code. This information is not useful when shipping final
Android apps to users and therefore, final builds should use the `--release`
flag to remove this debugging information to produce smaller dex files.

Typical invocations of D8 to produce dex file(s) in the out directoy:

Debug mode build:

    $ java -cp build/libs/r8.jar com.android.tools.r8.D8 \
           --min-api <min-api> \
           --output out \
           --lib <android.jar/rt.jar> \
           input.jar

Release mode build:

    $ java -cp build/libs/r8.jar com.android.tools.r8.D8
           --release \
           --min-api <min-api> \
           --output out \
           --lib <android.jar/rt.jar> \
           input.jar

See [Running R8](#running-r8) for information on options `--min-api` and `--lib`.

The full set of D8 options can be obtained by running the command line tool with
the `--help` option.

## <a name="running-r8"></a>Running R8

R8 is a whole-program optimizing compiler with focus on shrinking the size of
programs. R8 uses the
[ProGuard configuration format](https://www.guardsquare.com/manual/configuration/usage)
for configuring the whole-program optimization including specifying the entry points
for an application.

R8 consumes class files and can output either DEX for Android apps or class files
for Java apps.

Typical invocations of R8 to produce optimized DEX file(s) in the `out` directory:

    $ java -cp build/libs/r8.jar com.android.tools.r8.R8 \
           --release \
           --min-api <min-api> \
           --output out \
           --pg-conf proguard.cfg \
           --lib <android.jar/rt.jar> \
           input.jar

This produce DEX targeting Android devices with a API level of `<min-api>` and above.

The option `--lib` is passing the bootclasspath for the targeted runtime.
For targeting Android use an `android.jar` from the Android Platform SDK, typically
located in `~/Android/Sdk/platforms/android-XX`, where `XX` should be the latest
Android version.

To produce class files pass the option `--classfile` and leave out `--min-api <min-api>`.
This invocation will provide optimized Java classfiles in `output.jar`:

    $ java -cp build/libs/r8.jar com.android.tools.r8.R8 \
           --release \
           --classfile \
           --output output.jar \
           --pg-conf proguard.cfg \
           --lib <android.jar/rt.jar> \
           input.jar


When producing output targeted for the JVM one can pass `$JAVA_HOME` to `-lib`.
R8 will then locate the Java bootclasspath from there.

The full set of R8 options can be obtained by running the command line tool with
the `--help` option.

R8 is not command line compatible with ProGuard, for instance keep rules cannot be passed
on the command line, but have to be passed in a file using the `--pg-conf` option.

## <a name="replacing-r8-in-agp"></a>Replacing R8 in Android Gradle plugin

Android Gradle plugin (AGP) ships with R8 embedded (as part of the `builder.jar` from
`com.android.tools.build:builder:<agp version>` on https://maven.google.com).

To override the embedded version with a prebuilt R8 stable or `-dev` version, merge
the following into the top level `settings.gradle` or `settings.gradle.kts`:
```
pluginManagement {
    buildscript {
        repositories {
            google()
            mavenCentral()
        }
        dependencies {
            classpath("com.android.tools:r8:<version>")
        }
    }
}
```
To override the embedded version with a downloaded or freshly built `<path>/r8.jar` merge
the following into the top level `settings.gradle` or `settings.gradle.kts`:
```
pluginManagement {
    buildscript {
        dependencies {
            classpath(files("<path>/r8.jar"))
        }
    }
}
```
To override the embedded version with a version built from a specific hash on
the main branch merge the following into the top level `settings.gradle` or
`settings.gradle.kts`:
```
pluginManagement {
    buildscript {
        repositories {
            mavenCentral()
            maven {
                url = uri("https://storage.googleapis.com/r8-releases/raw/main")
            }
        }
        dependencies {
            classpath("com.android.tools:r8:<hash>")
        }
    }
}
```

## Testing

Typical steps to run tests:

    $ tools/test.py --no_internal

The `tools/test.py` script will use depot_tools to download a lot of tests
and test dependencies on the first run. This includes prebuilt version of the
art runtime on which to validate the produced dex code.

## Contributing

In order to contribute to D8/R8 you have to sign the
[Contributor License Agreement](https://cla.developers.google.com/about/google-individual).
If your contribution is owned by your employer you need the
[Corporate Contributor License Agreement](https://cla.developers.google.com/about/google-corporate).

Signing the CLA should be enough to be approved as a contributer. However, please send an email to
[r8-dev@googlegroups.com](mailto:r8-dev@googlegroups.com) to introduce yourself and your plans
for contributing to the project.

To create an account for the code review tool (required for uploading changes)
please navigate to https://r8-review.googlesource.com/ and sign in with the
account used to sign the CLA. First time you do that you will be asked to
_Create Gerrit Account_. Plase follow that process.

To create a branch for a change we recommend to use the `new-branch` git command from the
Chromium `depot_tools`:

    $ git new-branch my-change

This will make a branch of `origin/main`, so remember to run `git fetch origin main` first.
Make you changes and commit locally. Once you have a change that you are happy with
you should make sure that it passes all tests and then upload the change to our code
review tool using:

    $ git cl upload

On your first upload you will be asked to acquire credentials. Follow the
instructions given by `git cl upload` (as of Aug 5 2025 that is running
`git credential-luci login`, the previous `.gitcookies` based authentication
scheme has been deprecated.).

On successful uploads a link to the code review is printed in the
output of the `git cl upload` command. In the code review tool you can
assign reviewers and mark the change ready for review. At that
point the code review tool will send emails to reviewers.

## Getting help

For questions, reach out to us at
[r8-dev@googlegroups.com](mailto:r8-dev@googlegroups.com).

For D8, find known issues in the
[D8 issue tracker](https://issuetracker.google.com/issues?q=componentid:317603)
or file a new
[D8 bug report](https://issuetracker.google.com/issues/new?component=317603).

For R8, find known issues in the
[R8 issue tracker](https://issuetracker.google.com/issues?q=componentid:326788)
or file a new
[R8 bug report](https://issuetracker.google.com/issues/new?component=326788).