The new experimental plugin is based on Gradle’s new component model mechanism, while allows significant reduction in configuration time. It also includes NDK integration for building JNI applications. This user guides provides details on how to use it and highlights the difference between the new plugin and the original plugin.
Additionally, the DSL is likely change significantly, as APIs to create the DSL are finalized.
Requirements
- Gradle 2.5 only
- Android NDK r10e (if you are using NDK)
- SDK with Build Tools at least version 19.0.0 and we aim to minimize the amount of changes needed for the migration process in the future. Some features may require a more recent version.
Migrating from Traditional Android Gradle Plugin
A typical Android Studio project may have a directory structure as follows. File that needs to be change is highlighted in red:
There are some significant changes in the DSL between the new plugin and the traditional one.
.
├── app/
│ ├── app.iml
│ ├── build.gradle
│ └── src/
├── build.gradle
├── gradle/
│ └── wrapper/
│ ├── gradle-wrapper.jar
│ └── gradle-wrapper.properties
├── gradle.properties
├── gradlew*
├── gradlew.bat
├── local.properties
├── MyApplication.iml
└── settings.gradle
./gradle/wrapper/gradle-wrapper.properties
#Wed Apr 10 15:27:10 PDT 2013
distributionBase=GRADLE_USER_HOME
distributionPath=wrapper/dists
zipStoreBase=GRADLE_USER_HOME
zipStorePath=wrapper/dists
distributionUrl=https\://services.gradle.org/distributions/gradle-2.5-all.zip
./build.gradle
// Top-level build file where you can add configuration options common to all sub-projects/modules.
buildscript {
repositories {
jcenter()
}
dependencies {
classpath "com.android.tools.build:gradle-experimental:0.2.1"
// NOTE: Do not place your application dependencies here; they belong
// in the individual module build.gradle files
}
}
allprojects {
repositories {
jcenter()
}
}
./app/build.gradle
There are significant changes to the DSL of the plugin. We understand that many of the changes are frustrating and seem unnecessary, and our goal is to remove some of these current changes to minimize the migration process from the traditional plugin in the future.
DSL Changes:
-
Plugin name is com.android.model.application instead of com.android.application. Or use apply plugin: "com.android.model.library" if you want to create an Android aar library.
-
Configuration is wrapped with the model { } block
-
Most properties require the = operator
-
Adding elements to a Collection should be done using the add method.
Current DSL Limitations that will hopefully go away:
-
buildTypes, productFlavors and signingConfigs must be place outside of the android { } block.
-
Nested options within the android { } block must be configured using the with keyword.
-
Properties are only set with their direct types only, with no way to accept other types and adapting them. For instance:
-
Creating a buildType or productFlavor requires calling the create method. Modifying an existing one such as the release and debug buildType can be done using the just the name.
-
The DSL for modifying variants and their tasks is very, very limited right now.
apply plugin: "com.android.model.application"
model {
android {
compileSdkVersion = 22
buildToolsVersion = "22.0.1"
defaultConfig.with {
applicationId = "com.example.user.myapplication"
minSdkVersion.apiLevel = 15
targetSdkVersion.apiLevel = 22
versionCode = 1
versionName = "1.0"
buildConfigFields.with { create() { type = "int" name = "VALUE" value = "1" } }
}
}
android.buildTypes {
release {
minifyEnabled = false
proguardFiles.add(file("proguard-rules.pro"))
}
}
android.productFlavors {
create("flavor1") {
applicationId = "com.app"
}
}
// Configures source set directory.
android.sources {
main {
java {
source {
srcDir "src"
}
}
}
}
}
dependencies {
compile fileTree(dir: "libs", include: ["*.jar"])
compile "com.android.support:appcompat-v7:22.2.0"
}
Ndk Integration
The experimental plugin comes with NDK integration for creating native applications. To use the NDK integration:
-
Use the SDK Manager inside Studio to download the NDK.
-
Set ndk.dir in local.properties or the ANDROID_NDK_HOME environment variable to the directory containing the NDK.
-
Add an android.ndk block to the model in build.gradle.
Known Limitations
-
There’s no support for NDK-only modules. The only supported project types are hybrid app projects and hybrid Library Projects.
-
Consumed Library project don’t impact compilation of jni code in the consuming project (ie the AAR so files are simply packaged in the APK)
-
No support for creating and depending on static libraries
-
No support for using a NDK modules like cpu_features
-
No support for integrating external build systems.
The build.gradle of a simple NDK application may look like this:
apply plugin: 'com.android.model.application'
model {
android {
compileSdkVersion = 22
buildToolsVersion = "22.0.1"
}
android.ndk {
moduleName = "native"
}
}
*Note that the moduleName is required. It determines the name of the resulting native library.
By default, it will look in src/main/jni for C/C++ file. Configure android.sources to change the source directory.
model {
android {
compileSdkVersion = 22
buildToolsVersion = "22.0.1"
}
android.ndk {
moduleName = "native"
}
android.sources {
main {
jni {
source {
srcDir "src"
}
}
}
}
}
Various build options can be set within the android.ndk { } block. For example,
model {
android {
compileSdkVersion = 22
buildToolsVersion = "22.0.1"
}
android.ndk {
// All configurations that can be changed in android.ndk.
moduleName = "native"
toolchain = "clang"
toolchainVersion = "3.5"
// Note that CFlags has a capital C, which is inconsistent with
// the naming convention of other properties. This is a
// technical limitation that will be resolved
CFlags.add("-DCUSTOM_DEFINE")
cppFlags.add("-DCUSTOM_DEFINE")
ldFlags.add("-L/custom/lib/path")
ldLibs.add("log")
stl = "stlport_static"
}
android.buildTypes {
release {
ndk.with {
debuggable = true
}
}
}
android.productFlavors {
create("arm") {
ndk.with {
// You can customize the NDK configurations for each
// productFlavors and buildTypes.
abiFilters.add("armeabi-v7a")
}
}
create("fat") {
// If ndk.abiFilters is not configured, the application
// compile and package all suppported ABI.
}
}
// You can modify the NDK configuration for each variant.
components.android {
binaries.afterEach { binary ->
binary.mergedNdkConfig.cppFlags.add(
"-DVARIANT=\"" + binary.name + "\"")
}
}
}
Samples
Additional samples
can be found at
https://github.com/googlesamples/android-ndk
.
Multiple NDK Projects
Plugin 0.4.0 added the preliminary support for NDK dependencies and the ability to create just a native library. Please be aware this is a preview of the direction we are going and the implementation is not complete. Note that while it is possible to compile the native project for Gradle, editing and debugging support in Android Studio is not yet implemented.
Standalone NDK Plugin
In gradle-experimental:0.4.0, a new plugin is created to allow creation of just the native library without creating an Android application or library. The DSL is similar to the application/library plugin. The following example build.gradle can create a libhello.so from sources in "src/main/jni"
apply plugin: "com.android.model.native"
model {
android {
compileSdkVersion = 21
}
android.ndk {
moduleName = "hello"
}
}
Known Issues
-
Editing support for the standalone plugin is not yet implemented in Android Studio
-
Modifying a source file in the library does not automatically cause the application to re-link the new library when building an application.
NDK Dependencies
The syntax for specifying dependency follows the style of Gradle's future dependency system. You can set a dependency on an Android project or a specific file.
For example, let say you have a subproject in "lib" using the standalone NDK plugin:
lib/build.gradle:
apply plugin: "com.android.model.native"
model {
android {
compileSdkVersion = 21
}
android.ndk {
moduleName = "hello"
}
}
You can add dependency on the lib project from your application for your JNI code:
app/build.gradle:
apply plugin: "com.android.model.application"
model {
android {
compileSdkVersion = 23
buildToolsVersion = "23.0.0"
}
android.sources {
main {
jni {
dependencies {
project ":lib1"
}
}
}
}
}
You can specify a build type and/or product flavor of your target project. Otherwise, the plugin will try to find the same build types and product flavor as your application. You can also specify the linkage type if you would like the native library to be linked statically. E.g.
model {
android.sources {
main {
jni {
dependencies {
project ":lib1" buildType "debug" productFlavor "flavor1" linkage "static"
}
}
}
}
}
To declare a dependency on a file, you will also need to specify the ABI. E.g.,
model {
android.sources {
main {
jni {
dependencies {
library file("prebuilt.so") abi "x86"
}
}
}
}
}
Caveat: The next version will have a DSL change to follow Gradle's built in support for prebuilt library, similar to https://github.com/gradle/gradle/blob/master/subprojects/docs/src/samples/native-binaries/prebuilt/build.gradle.
You can add native dependency to either 'jniLibs' or 'jni' source set. When dependency is added to "jniLibs" the native library will be package into the application/library, but it will not be used for compiling the JNI code. E.g.
model {
android.sources {
main {
jniLibs {
dependencies {
library file("prebuilt.so") abi "x86"
}
}
}
}
}