Open source android_device rule.

This rule has an implicit dependency on unified_launcher, which is hosted in an external repository at https://github.com/google/android-testing-support-library and must be set up in the WORKSPACE file with repository name @android_test_support. A future change will introduce an Android tools set-up macro that will create workspace rules for all of the remote Android tools, including unified_launcher.

Note that unified_launcher is not supported on Mac or Windows, so Bazel will only be able to successfully build the android_device rule on Linux.

Instructions to set up unified_launcher for use with android_device:
1. Install xvfb
2. In your WORKSPACE add

```
android_sdk_repository(name = "androidsdk")  # Also set $ANDROID_HOME
git_repository(
    name = "android_test_support",
    remote = "https://github.com/google/android-testing-support-library",
    commit = "79725fed7a6884074fb3647a683869e7141ecf64",
)
load(
    "@android_test_support//tools/android/emulator:unified_launcher.bzl",
    load_unified_launcher_deps = "load_workspace")
load_unified_launcher_deps()
```

In your BUILD file, you can create an android_device rule for a system image that you have installed in your Android SDK as:

```
android_device(
    name = "my_device",
    cache = 256,
    default_properties = "@bazel_tools//tools/android/emulator:no_se_linux.properties",
    horizontal_resolution = 640,
    vertical_resolution = 800,
    screen_density = 133,
    ram = 2048,
    vm_heap = 256,
    system_image = "@androidsdk//:android-23_default_x86_files",
)

```

RELNOTES: Introduces experimental android_device rule for configuring and launching Android emulators.

PiperOrigin-RevId: 151766489

1 files changed, 212 insertions, 0 deletions

diff --git a/src/main/java/com/google/devtools/build/lib/rules/android/AndroidDeviceRule.java b/src/main/java/com/google/devtools/build/lib/rules/android/AndroidDeviceRule.java
new file mode 100644
index 0000000000..5b3cf6f1df
--- /dev/null
+++ b/src/main/java/com/google/devtools/build/lib/rules/android/AndroidDeviceRule.java
@@ -0,0 +1,212 @@
+// Copyright 2017 The Bazel Authors. All rights reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//    http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+package com.google.devtools.build.lib.rules.android;
+
+import static com.google.devtools.build.lib.packages.Attribute.ConfigurationTransition.HOST;
+import static com.google.devtools.build.lib.packages.Attribute.attr;
+import static com.google.devtools.build.lib.packages.BuildType.LABEL;
+import static com.google.devtools.build.lib.packages.BuildType.LABEL_LIST;
+import static com.google.devtools.build.lib.syntax.Type.BOOLEAN;
+import static com.google.devtools.build.lib.syntax.Type.INTEGER;
+
+import com.google.devtools.build.lib.analysis.BaseRuleClasses;
+import com.google.devtools.build.lib.analysis.RuleDefinition;
+import com.google.devtools.build.lib.analysis.RuleDefinitionEnvironment;
+import com.google.devtools.build.lib.packages.RuleClass;
+import com.google.devtools.build.lib.rules.java.JavaSemantics;
+
+/**
+ * Rule definition for android_device.
+ */
+public final class AndroidDeviceRule implements RuleDefinition {
+  @Override
+  public RuleClass build(RuleClass.Builder builder, RuleDefinitionEnvironment env) {
+    return builder
+        /* <!-- #BLAZE_RULE(android_device).IMPLICIT_OUTPUTS -->
+        <ul>
+          <li><code><var>name</var>_images/userdata.dat</code>:
+          Contains image files and snapshots to start the emulator</li>
+          <li><code><var>name</var>_images/emulator-meta-data.pb</code>:
+          Contains serialized information necessary to pass on to the emulator to
+          restart it.</li>
+        </ul>
+        <!-- #END_BLAZE_RULE.IMPLICIT_OUTPUTS --> */
+
+        /* <!-- #BLAZE_RULE(android_device).ATTRIBUTE(vertical_resolution) -->
+        The vertical screen resolution in pixels to emulate.
+        The minimum value is 240.
+        <!-- #END_BLAZE_RULE.ATTRIBUTE --> */
+        .add(attr("vertical_resolution", INTEGER).mandatory())
+        /* <!-- #BLAZE_RULE(android_device).ATTRIBUTE(horizontal_resolution) -->
+        The horizontal screen resolution in pixels to emulate.
+        The minimum value is 240.
+        <!-- #END_BLAZE_RULE.ATTRIBUTE --> */
+        .add(attr("horizontal_resolution", INTEGER).mandatory())
+        /* <!-- #BLAZE_RULE(android_device).ATTRIBUTE(ram) -->
+        The amount of ram in megabytes to emulate for the device.
+        This is for the entire device, not just for a particular app installed on the device. The
+        minimum value is 64 megabytes.
+        <!-- #END_BLAZE_RULE.ATTRIBUTE --> */
+        .add(attr("ram", INTEGER).mandatory())
+        /* <!-- #BLAZE_RULE(android_device).ATTRIBUTE(screen_density) -->
+        The density of the emulated screen in pixels per inch.
+        The minimum value of this is 30 ppi.
+        <!-- #END_BLAZE_RULE.ATTRIBUTE --> */
+        .add(attr("screen_density", INTEGER).mandatory())
+        /* <!-- #BLAZE_RULE(android_device).ATTRIBUTE(cache) -->
+        The size in megabytes of the emulator's cache partition.
+        The minimum value of this is 16 megabytes.
+        <!-- #END_BLAZE_RULE.ATTRIBUTE --> */
+        .add(attr("cache", INTEGER).mandatory())
+        /* <!-- #BLAZE_RULE(android_device).ATTRIBUTE(vm_heap) -->
+        The size in megabytes of the virtual machine heap Android will use for each process.
+        The minimum value is 16 megabytes.
+        <!-- #END_BLAZE_RULE.ATTRIBUTE --> */
+        .add(attr("vm_heap", INTEGER).mandatory())
+        /* <!-- #BLAZE_RULE(android_device).ATTRIBUTE(system_image) -->
+        A filegroup containing the following files:
+        <ul>
+        <li>system.img: The system partition.</li>
+        <li>kernel-qemu: The Linux kernel the emliator will load</li>
+        <li>ramdisk.img: The initrd image to use at boot time</li>
+        <li>userdata.img: The initial userdata partition.</li>
+        <li>source.properties: A properties file containing information about the
+        images</li>
+        </ul>
+        These files are part of the android sdk or provided by third parties (for
+        example Intel provides x86 images).
+        <!-- #END_BLAZE_RULE.ATTRIBUTE --> */
+        .add(attr("system_image", LABEL).mandatory().legacyAllowAnyFileType())
+        /* <!-- #BLAZE_RULE(android_device).ATTRIBUTE(default_properties) -->
+        A single properties file to be placed in /default.prop on the emulator.
+        This allows the rule author to further configure the emulator to appear more like
+        a real device (In particular controlling its UserAgent strings and other
+        behaviour that might cause an application or server to behave differently to
+        a specific device). The properties in this file will override read only
+        properties typically set by the emulator such as ro.product.model.
+        <!-- #END_BLAZE_RULE.ATTRIBUTE --> */
+        .add(attr("default_properties", LABEL).cfg(HOST)
+            .allowedFileTypes(JavaSemantics.PROPERTIES))
+        /* <!-- #BLAZE_RULE(android_device).ATTRIBUTE(platform_apks) -->
+        A list of apks to be installed on the device at boot time.
+        <!-- #END_BLAZE_RULE.ATTRIBUTE --> */
+        .add(attr("platform_apks", LABEL_LIST).legacyAllowAnyFileType())
+        .add(attr("$adb_static", LABEL).cfg(HOST).value(
+            env.getToolsLabel("//tools/android:adb_static")))
+        .add(attr("$adb", LABEL).cfg(HOST).value(
+            env.getToolsLabel("//tools/android:adb")))
+        .add(attr("$emulator_arm", LABEL).cfg(HOST).value(
+            env.getToolsLabel("//tools/android/emulator:emulator_arm")))
+        .add(attr("$emulator_x86", LABEL).cfg(HOST).value(
+            env.getToolsLabel("//tools/android/emulator:emulator_x86")))
+        .add(attr("$emulator_x86_bios", LABEL).cfg(HOST).value(
+            env.getToolsLabel("//tools/android/emulator:emulator_x86_bios")))
+        .add(attr("$mksd", LABEL).cfg(HOST).exec().value(
+            env.getToolsLabel("//tools/android/emulator:mksd")))
+        .add(attr("$empty_snapshot_fs", LABEL).cfg(HOST).value(
+            env.getToolsLabel("//tools/android/emulator:empty_snapshot_fs")))
+        .add(attr("$xvfb_support", LABEL).cfg(HOST).value(
+            env.getToolsLabel("//tools/android/emulator:xvfb_support")))
+        .add(attr("$unified_launcher", LABEL).cfg(HOST).exec().value(
+            env.getToolsLabel("//tools/android/emulator:unified_launcher")))
+        .add(attr("$android_runtest", LABEL).cfg(HOST).exec().value(
+            env.getToolsLabel("//tools/android:android_runtest")))
+        .add(attr("$testing_shbase", LABEL).cfg(HOST).exec().value(
+            env.getToolsLabel("//tools/android/emulator:shbase")))
+        .add(attr("$sdk_path", LABEL).cfg(HOST).exec().value(
+            env.getToolsLabel("//tools/android/emulator:sdk_path")))
+        .add(attr("$is_executable", BOOLEAN).value(true)
+            .nonconfigurable("Called from RunCommand.isExecutable, which takes a Target"))
+        .removeAttribute("deps")
+        .removeAttribute("data")
+        .build();
+  }
+
+  @Override
+  public Metadata getMetadata() {
+    return RuleDefinition.Metadata.builder()
+        .name("android_device")
+        .ancestors(BaseRuleClasses.RuleBase.class)
+        .factoryClass(AndroidDevice.class)
+        .build();
+  }
+}
+
+/*<!-- #BLAZE_RULE (NAME = android_device, TYPE = OTHER, FAMILY = Android) -->
+
+<p>This rule creates an android emulator configured with the given
+  specifications. This emulator may be started via a blaze run
+  command or by executing the generated script directly. It is encouraged to depend
+  on existing android_device rules rather than defining your own.
+</p>
+<p>This rule is a suitable target for the --run_under flag to blaze test and blaze
+  run.  It starts an emulator, copies the target being tested/run to the emulator,
+  and tests it or runs it as appropriate.
+</p>
+<p><code>android_device</code> supports creating KVM images if the underlying
+  <a href="${link android_device.system_image}">system_image</a> is X86 based and is
+  optimized for at most the I686 CPU architecture. To use KVM add
+  <code> tags = ['requires-kvm'] </code> to the <code>android_device</code> rule.
+</p>
+
+${IMPLICIT_OUTPUTS}
+
+<h4 id="android_device_examples">Examples</h4>
+
+<p>The following example shows how to use android_device.
+<code>//java/android/helloandroid/BUILD</code> contains</p>
+<pre class="code">
+android_device(
+    name = "nexus_s",
+    cache = 32,
+    default_properties = "nexus_s.properties",
+    horizontal_resolution = 480,
+    ram = 512,
+    screen_density = 233,
+    system_image = ":emulator_images_android_16_x86",
+    vertical_resolution = 800,
+    vm_heap = 32,
+)
+
+filegroup(
+    name = "emulator_images_android_16_x86",
+    srcs = glob(["androidsdk/system-images/android-16/**"]),
+)
+</pre>
+  <p><code>//java/android/helloandroid/nexus_s.properties</code> contains:</p>
+  <pre class="code">
+ro.product.brand=google
+ro.product.device=crespo
+ro.product.manufacturer=samsung
+ro.product.model=Nexus S
+ro.product.name=soju
+</pre>
+<p>
+  This rule will generate images and a start script. You can start the emulator
+  locally by executing blaze run :nexus_s -- --action=start. The script exposes
+  the following flags:
+</p>
+  <ul>
+    <li>--adb_port: The port to expose adb on. If you wish to issue adb
+    commands to the emulator this is the port you will issue adb connect
+    to.</li>
+    <li>--emulator_port: The port to expose the emulator's telnet management
+    console on.</li>
+    <li>--enable_display: Starts the emulator with a display if true (defaults
+    to false).</li>
+    <li>--action: Either start or kill.</li>
+    <li>--apks_to_install: a list of apks to install on the emulator.</li>
+  </ul>
+
+<!-- #END_BLAZE_RULE -->*/