| Ian Zerny | e85345e | 2020-12-17 11:19:30 +0100 | [diff] [blame] | 1 | # Compiler-input dumps |
| 2 | |
| 3 | The D8 and R8 compilers support generating a compiler-input dump for use in |
| 4 | reproducing compiler issues. |
| 5 | |
| 6 | |
| 7 | ## The content of a dump |
| 8 | |
| 9 | The dump contains almost all of the inputs that are given to the compiler as |
| 10 | part of compilation. In particular, it contains *all* class definitions in the |
| 11 | form of Java classfiles (i.e., bytecode, not the Java source files). |
| 12 | In addition to the classfiles, the dump also includes Java resources, the |
| 13 | compiler type, version, and flags, such as `--debug` or `--release`, |
| 14 | main-dex lists or rules, and more. For R8 the dump also contains the full |
| 15 | concatenation of all keep rules. |
| 16 | |
| 17 | The dump is a zip file containing the above. You should unzip it and review |
| 18 | the content locally. The program, classpath and library content will be in |
| 19 | nested zip files. The remaining content is in plain text files. |
| 20 | |
| 21 | |
| 22 | ## Generating a dump |
| 23 | |
| 24 | To generate a dump file, run the compiler with the |
| 25 | `com.android.tools.r8.dumpinputtofile` system property set: |
| 26 | |
| 27 | ``` |
| 28 | java -cp r8.jar -Dcom.android.tools.r8.dumpinputtofile=mydump.zip com.android.tools.r8.D8 <other-compiler-args> |
| 29 | ``` |
| 30 | |
| 31 | This will generate a dump file `mydump.zip` and exit the compiler with a |
| 32 | non-zero exit value printing an error message about the location of the dump |
| 33 | file that was written. |
| 34 | |
| 35 | For some builds, there may be many compilations taking place which cannot be |
| 36 | easily isolated as individual compilation steps. If so, the system property |
| 37 | `com.android.tools.r8.dumpinputtodirectory` can be set to a directory instead. |
| 38 | Doing so will dump the inputs of each compilation to the directory in |
| 39 | individual zip files and they will be named using a timestamp in an attempt |
| 40 | to maintain an order. The compiler will compile as usual thus not disrupting |
| 41 | the build. |
| 42 | |
| 43 | ### Generating a dump with Gradle and the Android Studio Plugin |
| 44 | |
| 45 | To generate a dump from studio, the system property should be set for the |
| 46 | build command. This can typically be done by amending the command-line gradle |
| 47 | build-target command. Say your build target is `assembleRelease`, you would run: |
| 48 | |
| 49 | ``` |
| 50 | ./gradlew assembleRelease -Dcom.android.tools.r8.dumpinputtofile=mydump.zip --no-daemon |
| 51 | ``` |
| 52 | |
| 53 | If the build is a debug build, such as `assembleDebug`, then it will likely be an |
| 54 | incremental D8 build in which case the best option is to provide a dump |
| 55 | directory and then locate the particular dump file associated with the |
| 56 | problematic compilation (if the compilation fails, the interesting dump will |
| 57 | hopefully be the last dump): |
| 58 | |
| 59 | ``` |
| 60 | ./gradlew assembleDebug -Dcom.android.tools.r8.dumpinputtodirectory=mydumps/ --no-daemon |
| 61 | ``` |
| 62 | |
| 63 | |
| 64 | ## Reproducing using a dump |
| 65 | |
| 66 | To reproduce a compiler issue with a dump use the script `tools/compiledump.py` |
| 67 | from the R8 repository. Note that the script is *not* a standalone script so you |
| 68 | will need a full checkout of the R8 project. |
| 69 | |
| 70 | Reproducing should then be just: |
| 71 | ``` |
| 72 | ./tools/compiledump.py -d mydump.zip |
| 73 | ``` |
| 74 | |
| 75 | Depending on the compiler version that generated the dump additional flags may |
| 76 | be needed to specify the compiler and its version. Run `--help` for a list of |
| 77 | options. |
| 78 | |
| 79 | The flags can also be used to override the setting specified in the dump. |
| 80 | Doing so allows compiling with other compiler versions, or other settings. |
