chrome/android/java/README.md

## //chrome/android/java/*proguard_flags.expected files

### Proguard flags

[Proguard](https://www.guardsquare.com/en/products/proguard) is used in the
build to obfuscate and minify Java code.

Proguard flags (also known as configs or rules) are used to specify which parts
of Java code should not be optimized/obfuscated/modified by Proguard.

For example, the following rule specifies that all public classes with a
`public static void main(java.lang.String[])` method should not be modifed.

```
-keepclasseswithmembers public class * {
    public static void main(java.lang.String[]);
}
```

### What are `*.proguard_flags.expected` files?

[monochrome_public_apk.proguard_flags.expected](monochrome_public_apk.proguard_flags.expected)
contains all proguard configs used when building MonochromePublic.apk, and is
generated by the `proguard()` build step.

### Why do we care about proguard flag discrepancies?

Some configs are explicitly added ([ex](proguard.flags)) while others are pulled
in implicitly by GN deps (ex. `aar_prebuilt()` deps). In the later case, these
config changes aren't reviewed and can sometimes result in crashes and/or size
regressions. Example of where this has happened before:

  * Updating a prebuilt that supplies a Proguard config with a rule that is
    too broad (i.e. a rule that matches more classes than the intended ones)

Having checked-in versions of the Proguard configs used allows us to identify
and address these issues earlier.

### What is the build error telling me?

The build error is indicating that your CL has caused proguard rules to be
added/removed/changed and that the expected file needs to be updated.

### Fixing build failures

1. Ensure your args.gn contains these args:
```
enable_chrome_android_internal = false
is_java_debug = false
```

2. Run:

```
autoninja -C $CHROMIUM_OUTPUT_DIR monochrome_public_apk
```

3. Run the command suggested in the error message to copy the contents of the
   generated proguard config file to the expected config file.

4. Add the updated `.expected` file to your CL

5. Afterwards, you can revert the args.gn changes suggested above and build
   normally

### Trybot failures

On the [android-binary-size](https://ci.chromium.org/p/chromium/builders/luci.chromium.try/android-binary-size)
trybot we set `check_android_configuration=true` which causes any differences
between the expected and generated Proguard configs to fail the build.

Without this argument the error message is shown but doesn't fail the build.

### Troubleshooting

Trybots fail but you can't reproduce locally

* If a public target is failing, double check to make sure you've set
  `enable_chrome_android_internal=false`

Can't find the file suggested by the error message

* Make sure `is_java_debug=false`

Updating the file doesn't fix the error

* Make sure you're building `monochrome_public_apk`

Otherwise, please file a bug at [crbug.com/new](https://crbug.com/new) and/or
message estevenson@.