From c3c4f36d90f33cedc61a22ffd34daa72a36f1f7d Mon Sep 17 00:00:00 2001 From: ajmichael Date: Mon, 15 May 2017 21:11:00 +0200 Subject: [PATCH] Document android_sdk_repository. One step towards https://github.com/bazelbuild/bazel/issues/1272. RELNOTES: None PiperOrigin-RevId: 156086120 --- .../android/AndroidSdkRepositoryRule.java | 90 ++++++++++++++++++- 1 file changed, 86 insertions(+), 4 deletions(-) diff --git a/src/main/java/com/google/devtools/build/lib/bazel/rules/android/AndroidSdkRepositoryRule.java b/src/main/java/com/google/devtools/build/lib/bazel/rules/android/AndroidSdkRepositoryRule.java index b799293b846e65..6fb24feca062af 100644 --- a/src/main/java/com/google/devtools/build/lib/bazel/rules/android/AndroidSdkRepositoryRule.java +++ b/src/main/java/com/google/devtools/build/lib/bazel/rules/android/AndroidSdkRepositoryRule.java @@ -55,19 +55,41 @@ public Map apply(Rule rule) { @Override public RuleClass build(Builder builder, RuleDefinitionEnvironment environment) { return builder - .setUndocumented() .setWorkspaceOnly() .setExternalBindingsFunction(BINDINGS_FUNCTION) + /* + An absolute or relative path to an Android SDK. Either this attribute or the + $ANDROID_HOME environment variable must be set. + +

The Android SDK can be downloaded from + the Android developer site. + */ .add(attr("path", STRING).nonconfigurable("WORKSPACE rule")) // This is technically the directory for the build tools in $sdk/build-tools. In particular, // preview SDKs are in "$sdk/build-tools/x.y.z-preview", but the version is typically // actually "x.y.z-rcN". E.g., for 24, the directory is "$sdk/build-tools/24.0.0-preview", // but the version is e.g. "24 rc3". The android_sdk rule that is generated from // android_sdk_repository would need the real version ("24 rc3"). - // - // If build_tools_version is not specified explicitly, the highest build tools version - // installed will be used. + /* + The version of the Android build tools to use from within the Android SDK. If not specified, + the latest build tools version installed will be used. + +

Bazel requires build tools version 24.0.3 or later. + */ .add(attr("build_tools_version", STRING).nonconfigurable("WORKSPACE rule")) + /* + The Android API level to build against by default. If not specified, the highest API level + installed will be used. + +

The API level used for a given build can be overridden by the android_sdk + flag. android_sdk_repository creates an android_sdk target for + each API level installed in the SDK with name @androidsdk//:sdk-${level}, + whether or not this attribute is specified. For example, to build against a non-default API + level: bazel build --android_sdk=@androidsdk//:sdk-19 //java/com/example:app. + +

To view all android_sdk targets generated by android_sdk_repository + , you can run bazel query "kind(android_sdk, @androidsdk//...)". + */ .add(attr("api_level", INTEGER).nonconfigurable("WORKSPACE rule")) .build(); } @@ -82,3 +104,63 @@ public Metadata getMetadata() { .build(); } } + +/* + +

Configures Bazel to use a local Android SDK to support building Android targets.

+ +

Examples

+ +The minimum to set up an Android SDK for Bazel is to put an android_sdk_repository rule +named "androidsdk" in your WORKSPACE file and set the $ANDROID_HOME +environment variable to the path of your Android SDK. Bazel will use the highest Android API level +and build tools version installed in the Android SDK by default. + +
+android_sdk_repository(
+    name = "androidsdk",
+)
+
+ +

To ensure reproducible builds, the path, api_level and +build_tools_version attributes can be set to specific values. The build will fail if +the Android SDK does not have the specified API level or build tools version installed. + +

+android_sdk_repository(
+    name = "androidsdk",
+    path = "./sdk",
+    api_level = 19,
+    build_tools_version = "25.0.0",
+)
+
+ +

The above example also demonstrates using a workspace-relative path to the Android SDK. This is +useful if the Android SDK is part of your Bazel workspace (e.g. if it is checked into version +control). + + +

Support Libraries

+ +

The Support Libraries are available in the Android SDK Manager as "Android Support Repository". +This is a versioned set of common Android libraries, such as the Support and AppCompat libraries, +that is packaged as a local Maven repository. android_sdk_repository generates Bazel +targets for each of these libraries that can be used in the dependencies of +android_binary and android_library targets. + +

The names of the generated targets are derived from the Maven coordinates of the libraries in the +Android Support Repository, formatted as @androidsdk//${group}:${artifact}-${version}. +The following example shows how an android_library can depend on version 25.0.0 of the +v7 appcompat library. + +

+android_library(
+    name = "lib",
+    srcs = glob(["*.java"]),
+    manifest = "AndroidManifest.xml",
+    resource_files = glob(["res/**"]),
+    deps = ["@androidsdk//com.android.support:appcompat-v7-25.0.0"],
+)
+
+ +*/