1# View Compiler
2
3This directory contains an experimental compiler for layout files.
4
5It will take a layout XML file and produce a CompiledLayout.java file with a
6specialized layout inflation function.
7
8To use it, let's assume you had a layout in `my_layout.xml` and your app was in
9the Java language package `com.example.myapp`. Run the following command:
10
11    viewcompiler my_layout.xml --package com.example.myapp --out CompiledView.java
12
13This will produce a `CompiledView.java`, which can then be compiled into your
14Android app. Then to use it, in places where you would have inflated
15`R.layouts.my_layout`, instead call `CompiledView.inflate`.
16
17Precompiling views like this generally improves the time needed to inflate them.
18
19This tool is still in its early stages and has a number of limitations.
20* Currently only one layout can be compiled at a time.
21* `merge` and `include` nodes are not supported.
22* View compilation is a manual process that requires code changes in the
23  application.
24* This only works for apps that do not use a custom layout inflater.
25* Other limitations yet to be discovered.
26
27## DexBuilder Tests
28
29The DexBuilder has several low-level end to end tests to verify generated DEX
30code validates, runs, and has the correct behavior. There are, unfortunately, a
31number of pieces that must be added to generate new tests. Here are the
32components:
33
34* `dex_testcase_generator` - Written in C++ using `DexBuilder`. This runs as a
35  build step produce the DEX files that will be tested on device. See the
36  `genrule` named `generate_dex_testcases` in `Android.bp`. These files are then
37  copied over to the device by TradeFed when running tests.
38* `DexBuilderTest` - This is a Java Language test harness that loads the
39  generated DEX files and exercises methods in the file.
40
41To add a new DEX file test, follow these steps:
421. Modify `dex_testcase_generator` to produce the DEX file.
432. Add the filename to the `out` list of the `generate_dex_testcases` rule in
44   `Android.bp`.
453. Add a new `push` option to `AndroidTest.xml` to copy the DEX file to the
46   device.
474. Modify `DexBuilderTest.java` to load and exercise the new test.
48
49In each case, you should be able to cargo-cult the existing test cases.
50
51In general, you can probably get by without adding a new generated DEX file, and
52instead add more methods to the files that are already generated. In this case,
53you can skip all of steps 2 and 3 above, and simplify steps 1 and 4.
54