chrome/android/java/README.md

# //chrome/android/java/*.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_bundle.proguard_flags.expected](monochrome_public_bundle.proguard_flags.expected)
contains all proguard configs used when building MonochromePublic.aab, 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.

## AndroidManifest.xml

Each Android application has a manifest that contains information about the app
(ex. permissions required, services exposed, etc).

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

[monochrome_public_bundle__base_bundle_module.AndroidManifest.expected](monochrome_public_bundle__base_bundle_module.AndroidManifest.expected)
contains the contents of the final merged manifest used when building
MonochromePublic.aab.

### Why do we care about AndroidManifest discrepancies?

While most manifest changes are reviewed when the manifest template file
changes, manifest entries that are pulled in via. deps (through manifest
merging) can cause real bugs (permissions issues, security vulnerabilities).

## Build failures caused by `*.expected` files

### What is the build error telling me?

The build error is indicating that your CL has caused a mismatch between the
expected file and the generated file and that either the issue requires
attention or the expected file needs updating.

### Fixing build failures

#### Option A: Copy the expected file generated by the trybot

1. Click on the android-binary-size trybot failure in your CL

2. Click on the stdout link of the compile step

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

#### Option B: Update expected files with a local build

1. Ensure that:

   * Your args.gn contains these args:

   ```
   enable_chrome_android_internal = false
   is_java_debug = false
   android_channel = "stable"
   ```

   * Your local branch is up-to-date with master


2. Run:

   For AndroidManifest failures:

   ```
   autoninja -C $CHROMIUM_OUTPUT_DIR monochrome_public_bundle__base_bundle_module__merge_manifests
   ```

   For Proguard flags failures:

   ```
   autoninja -C $CHROMIUM_OUTPUT_DIR monochrome_public_bundle
   ```

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

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 files 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_bundle`

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