README.md - r8 - Git at Google

 # 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.

 D8 is a replacement for the DX dexer and R8 is an alternative to
 the [ProGuard](https://www.guardsquare.com/en/proguard) shrinking and
 minification tool.

 ## Obtaining prebuilts

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

 The stable release versions shipped with Android Studio are available from
 the Google Maven repository, see
 https://maven.google.com/web/index.html#com.android.tools:r8.

 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 bucket r8-releases.

 To obtain a prebuild from the CI for a specifc version (including both
 stable and `-dev` versions), download from the following URL:

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

 To obtain a prebuild from the CI for a specifc main branch hash, download 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 which has 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 using the following in a Gradle build file:

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

 See [Running D8](#running-d8) and [Running R8](#running-r8) below 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 project `r8/d8_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 with version `<version>`, 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")
             }
         }
         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"))
         }
     }
 }
 ```

 ## 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).

 Once the license agreement is in place, please send an email to
 [r8-dev@googlegroups.com](mailto:r8-dev@googlegroups.com) to be added as a
 contributor.

 After being added as a contributer you can upload your patches
 using `git cl` which is available in `depot_tools`. 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`.

 On successful uploads a link to the code review is printed in the
 output of the 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).
	# 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.

	D8 is a replacement for the DX dexer and R8 is an alternative to
	the [ProGuard](https://www.guardsquare.com/en/proguard) shrinking and
	minification tool.

	## Obtaining prebuilts

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

	The stable release versions shipped with Android Studio are available from
	the Google Maven repository, see
	https://maven.google.com/web/index.html#com.android.tools:r8.

	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 bucket r8-releases.

	To obtain a prebuild from the CI for a specifc version (including both
	stable and `-dev` versions), download from the following URL:

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

	To obtain a prebuild from the CI for a specifc main branch hash, download 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 which has 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 using the following in a Gradle build file:

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

	See [Running D8](#running-d8) and [Running R8](#running-r8) below 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 project `r8/d8_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 with version `<version>`, 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")
	}
	}
	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"))
	}
	}
	}
	```

	## 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).

	Once the license agreement is in place, please send an email to
	[r8-dev@googlegroups.com](mailto:r8-dev@googlegroups.com) to be added as a
	contributor.

	After being added as a contributer you can upload your patches
	using `git cl` which is available in `depot_tools`. 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`.

	On successful uploads a link to the code review is printed in the
	output of the 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).