blob: 1c5dc9f54b01346ab1bc25a3cdc93638e1a20979 [file] [log] [blame] [view]
Mads Ager4c9a7fa2017-06-16 11:28:58 +02001# D8 dexer and R8 shrinker
Mads Ager418d1ca2017-05-22 09:35:49 +02002
Mads Ager4c9a7fa2017-06-16 11:28:58 +02003The R8 repo contains two tools:
Mads Ager418d1ca2017-05-22 09:35:49 +02004
Mads Ager4c9a7fa2017-06-16 11:28:58 +02005- D8 is a dexer that converts java byte code to dex code.
6- R8 is a java program shrinking and minification tool that converts java byte
7 code to optimized dex code.
8
9D8 is a replacement for the DX dexer and R8 is a replacement for
10the [Proguard](https://www.guardsquare.com/en/proguard) shrinking and
11minification tool.
12
13## Downloading and building
14
15The R8 project uses [`depot_tools`](https://www.chromium.org/developers/how-tos/install-depot-tools)
16from the chromium project to manage dependencies. Install `depot_tools` and add it to
17your path before proceeding.
18
19The R8 project uses Java 8 language features and requires a Java 8 compiler
20and runtime system.
21
22Typical steps to download and build:
23
24
25 $ git clone https://r8.googlesource.com/r8
26 $ cd r8
27 $ tools/gradle.py d8 r8
28
29The `tools/gradle.py` script will bootstrap using depot_tools to download
30a version of gradle to use for building on the first run. This will produce
31two jar files: `build/libs/d8.jar` and `build/libs/r8.jar`.
32
33## Running D8
34
35The D8 dexer has a simple command-line interface with only a few options.
36
37The most important option is whether to build in debug or release mode. Debug
38is the default mode and includes debugging information in the resulting dex
39files. Debugging information contains information about local variables used
40when debugging dex code. This information is not useful when shipping final
41Android apps to users and therefore, final builds should use the `--release`
42flag to remove this debugging information to produce smaller dex files.
43
44Typical invocations of D8 to produce dex file(s) in the out directoy:
45
46Debug mode build:
47
48 $ java -jar build/libs/d8.jar --output out input.jar
49
50Release mode build:
51
52 $ java -jar build/libs/d8.jar --release --output out input.jar
53
54The full set of D8 options can be obtained by running the command line tool with
55the `--help` option.
56
57## Running R8
58
59R8 is a [Proguard](https://www.guardsquare.com/en/proguard) replacement for
60whole-program optimization, shrinking and minification. R8 uses the Proguard
61keep rule format for specifying the entry points for an application.
62
63Typical invocations of R8 to produce optimized dex file(s) in the out directory:
64
65 $ java -jar build/libs/r8.jar --release --output out --pg-conf proguard.cfg input.jar
66
67The full set of R8 options can be obtained by running the command line tool with
68the `--help` option.
69
70## Testing
71
72Typical steps to run tests:
73
74 $ tools/test.py --no_internal
75
76The `tools/test.py` script will use depot_tools to download a lot of tests
77and test dependencies on the first run. This includes prebuilt version of the
78art runtime on which to validate the produced dex code.
79
ager6e27cfb2017-09-29 09:47:52 -070080## Contributing
81
82In order to contribute to D8/R8 you have to sign the
83[Contributor License Agreement](https://cla.developers.google.com/about/google-individual).
84If your contribution is owned by your employer you need the
85[Corporate Contributor License Agreement](https://cla.developers.google.com/about/google-corporate).
86
87Once the license agreement is in place, you can upload your patches
88using 'git cl' which is available in depot_tools. Once you have a
89change that you are happy with you should make sure that it passes
90all tests and then upload the change to our code review tool using:
91
92 $ git cl upload
93
94On your first upload you will be asked to acquire credentials. Follow the
95instructions given by `git cl upload`.
96
97On successful uploads a link to the code review is printed in the
98output of the upload command. In the code review tool you can
99assign reviewers and mark the change ready for review. At that
100point the code review tool will send emails to reviewers.
101
Mads Ager4c9a7fa2017-06-16 11:28:58 +0200102## Getting help
103
Ian Zerny4ffb2c82017-12-11 10:54:13 +0100104For questions, reach out to us at r8-dev@googlegroups.com.
105
106For D8, find known issues in the
107[D8 issue tracker](https://issuetracker.google.com/issues?q=componentid:317603)
108or file a new
109[D8 bug report](https://issuetracker.google.com/issues/new?component=317603).
110
111For R8, find known issues in the
112[R8 issue tracker](https://issuetracker.google.com/issues?q=componentid:326788)
113or file a new
114[R8 bug report](https://issuetracker.google.com/issues/new?component=326788).