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