1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
chrome / android / expectations / README.md [blame]
# //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_64_32_public_bundle.proguard_flags.expected](monochrome_64_32_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, or any target that specifies
`proguard_configs = [...]`).
Since proguard configs are global in nature, it is important that all configs go
through code review. We use these `.expected` files to ensure that they do.
## 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?
They contain the pretty-printed contents of the final merged manifest used when
building their associated targets.
### What are `*.AndroidManifest.diff.expected` files?
For internal targets, we don't want to check that the generated manifest are
identical to a specified expectation file. Instead, we want to ensure that the
differences between the target's AndroidManifest and an expectation file are as
expected. In this case, we specify a `*.AndroidManifest.diff.expected` file to
store the expected differences.
The contents of the `*.AndroidManifest.diff.expected` file are lines that start
with '+'. We use ndiff diff format to diff the 2 manifests, which represents
differences by prepending '+' before new lines, '-' before deleted lines, and
keeping all common lines. To create a `*.AndroidManifest.diff.expected`,
we filter out all lines that don't start with '+' to avoid irrelevant upstream
changes to break downstream checks.
### 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).
`AndroidManfiest.xml` entries create a contract between Chrome and Android,
and so its important that all changes to this contract go through code review.
## Native Libraries and Assets
Some of our apk and aab files contain native library files (under lib/) and
assets files (under assets/).
### What are `*.native_libs_and_assets.expected` files?
`*.native_libs_and_assets.expected` files store in a text format the list of
native libraries & assets, and their related information (whether it's
compressed, how it's aligned).
### Why do we care about native libraries and assets discrepancies?
When we change build gn files, the native libraries and assets can sometimes
be changed in an unexpected way.
## 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 just:
```
use_remoteexec = true
target_os = "android"
enable_chrome_android_internal = false
target_cpu = "arm64"
android_channel = "stable"
is_official_build = true
```
2. Run:
```
rm $CHROMIUM_OUTPUT_DIR/failed_expectations/*
autoninja -C $CHROMIUM_OUTPUT_DIR validate_expectations
```
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
The [android-binary-size] trybot fails when expectations do not match. The one
exception is that arm64 native libs and assets expectations are checked by
[android-pie-arm64-rel].
[android-binary-size]: https://ci.chromium.org/p/chromium/builders/luci.chromium.try/android-binary-size
[android-pie-arm64-rel]: https://ci.chromium.org/p/chromium/builders/luci.chromium.try/android-pie-arm64-rel
### 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.