1# ART Chroot-Based On-Device Testing
2
3This file documents the use of a chroot environment in on-device testing of the
4Android Runtime (ART). Using a chroot allows tests to run a standalone ART from
5a locally built source tree on a device running (almost any) system image and
6does not interfere with the Runtime installed in the device's system partition.
7
8## Introduction
9
10The Android Runtime (ART) supports testing in a chroot-based environment, by
11setting up a chroot directory in a `ART_TEST_CHROOT` directory located under
12`/data/local` (e.g. `ART_TEST_CHROOT=/data/local/art-test-chroot`) on a device,
13installing ART and all other required artifacts there, and having tests use `adb
14shell chroot $ART_TEST_CHROOT <command>` to execute commands on the device
15within this environment.
16
17This way to run tests using a "standalone ART" ("guest system") only affects
18files in the data partition (the system partition and other partitions are left
19untouched) and is as independent as possible from the Android system ("host
20system") running on the device. This has some benefits:
21
22* no need to build and flash a whole device to do ART testing (or "overwriting"
23  an existing ART by syncing the system partition);
24* the possibility to use a smaller AOSP Android manifest
25  ([`master-art`](https://android.googlesource.com/platform/manifest/+/refs/heads/master-art/default.xml))
26  to build ART and the required dependencies for testing;
27* no instability due to updating/replacing ART on the system partition (a
28  functional Android Runtime is necessary to properly boot a device);
29* the possibility to have several standalone ART instances (one per directory,
30  e.g. `/data/local/art-test-chroot1`, `/data/local/art-test-chroot2`, etc.).
31
32Note that using this chroot-based approach requires root access to the device
33(i.e. be able to run `adb root` successfully).
34
35## Quick User Guide
36
370. Unset variables which are not used with the chroot-based approach (if they
38   were set previously):
39   ```bash
40   unset ART_TEST_ANDROID_ROOT
41   unset CUSTOM_TARGET_LINKER
42   unset ART_TEST_ANDROID_ART_ROOT
43   unset ART_TEST_ANDROID_RUNTIME_ROOT
44   unset ART_TEST_ANDROID_I18N_ROOT
45   unset ART_TEST_ANDROID_TZDATA_ROOT
46   ```
471. Set the chroot directory in `ART_TEST_CHROOT`:
48    ```bash
49    export ART_TEST_CHROOT=/data/local/art-test-chroot
50    ```
512. Set lunch target and ADB:
52    * With a minimal `aosp/master-art` tree:
53        ```bash
54        export SOONG_ALLOW_MISSING_DEPENDENCIES=true
55        . ./build/envsetup.sh
56        lunch armv8-eng  # or arm_krait-eng for 32-bit ARM
57        export PATH="$(pwd)/prebuilts/runtime:$PATH"
58        export ADB="$ANDROID_BUILD_TOP/prebuilts/runtime/adb"
59        ```
60    * With a full Android (AOSP) `aosp/master` tree:
61        ```bash
62        export OVERRIDE_TARGET_FLATTEN_APEX=true
63        . ./build/envsetup.sh
64        lunch aosp_arm64-eng  # or aosp_arm-eng for 32-bit ARM
65        m adb
66        ```
673. Build ART and required dependencies:
68    ```bash
69    art/tools/buildbot-build.sh --target
70    ```
714. Clean up the device:
72    ```bash
73    art/tools/buildbot-cleanup-device.sh
74    ```
755. Setup the device (including setting up mount points and files in the chroot directory):
76    ```bash
77    art/tools/buildbot-setup-device.sh
78    ```
796. Populate the chroot tree on the device (including "activating" APEX packages
80   in the chroot environment):
81    ```bash
82    art/tools/buildbot-sync.sh
83    ```
847. Run ART gtests:
85    ```bash
86    art/tools/run-gtests.sh -j4
87    ```
88    * Note: This currently fails on test
89    `test-art-target-gtest-image_space_test{32,64}` when using the full AOSP
90    tree (b/119815008).
91        * Workaround: Run `m clean-oat-host` before the build step
92        (`art/tools/buildbot-build.sh --target`) above.
93    * Note: The `-j` option is not honored yet (b/129930445).
94    * Specific tests to run can be passed on the command line, specified by
95    their absolute paths beginning with `/apex/`.
968. Run ART run-tests:
97    * On a 64-bit target:
98        ```bash
99        art/test/testrunner/testrunner.py --target --64
100        ```
101    * On a 32-bit target:
102        ```bash
103        art/test/testrunner/testrunner.py --target --32
104        ```
1059. Run Libcore tests:
106    * On a 64-bit target:
107        ```bash
108        art/tools/run-libcore-tests.sh --mode=device --variant=X64
109        ```
110    * On a 32-bit target:
111        ```bash
112        art/tools/run-libcore-tests.sh --mode=device --variant=X32
113        ```
11410. Run JDWP tests:
115    * On a 64-bit target:
116        ```bash
117        art/tools/run-libjdwp-tests.sh --mode=device --variant=X64
118        ```
119    * On a 32-bit target:
120        ```bash
121        art/tools/run-libjdwp-tests.sh --mode=device --variant=X32
122        ```
12311. Tear down device setup:
124    ```bash
125    art/tools/buildbot-teardown-device.sh
126    ```
12712. Clean up the device:
128    ```bash
129    art/tools/buildbot-cleanup-device.sh
130    ```
131