USING HARDWARE DEVICES

USING HARDWARE DEVICES

• When building a mobile application, it's important that you always test your application on a real device before releasing it to users. This page describes how to set up your development environment and Android-powered device for testing and debugging on the device.

• You can use any Android-powered device as an environment for running, debugging, and testing your applications. The tools included in the SDK make it easy to install and run your application on the device each time you compile. You can install your application on the device directly from Android Studio or from the command line with ADB. If you don't yet have a device, check with the service providers in your area to determine which Android-powered devices are available.

NOTE

• When developing on a device, keep in mind that you should still use the Android emulator to test your application on configurations that are not equivalent to those of your real device. • Although the emulator does not allow you to test every

device feature (such as the accelerometer), it does allow you to verify that your application functions properly on different versions of the Android platform, in different screen sizes and orientations, and more.

ENABLING ON-DEVICE DEVELOPER OPTIONSAndroid-powered devices have a host of developer options that you can access on the phone, which let you:• Enable debugging over USB.• Quickly capture bug reports onto the device.• Show CPU usage on screen.• Draw debugging information on screen such as layout bounds, updates on GPU

views and hardware layers, and other information.• Plus many more options to simulate app stresses or enable debugging options.

ENABLING ON-DEVICE DEVELOPER OPTIONS• To access these settings, open the Developer options in the

system Settings. • On Android 4.2 and higher, the Developer options screen is

hidden by default. To make it visible, go to:Settings > About phone and tap Build number seven times.

Return to the previous screen to find Developer options at the bottom.

SETTING UP A DEVICE FOR DEVELOPMENT

With an Android-powered device, you can develop and debug your Android applications just as you would on the emulator. Before you can start, there are just a few things to do:1. Verify that your application is "debuggable" in your manifest or

build.gradle file.In the build file, make sure the debuggable property in the debug build type is set to true. The build type property overrides the manifest setting.

android { buildTypes { debug { debuggable true }

SETTING UP A DEVICE FOR DEVELOPMENT

• In the AndroidManifest.xml file, add android:debuggable="true" to the <application> element.• Note: If you manually enable debugging in the manifest file,

be sure to disable it in your release build (your published application should usually not be debuggable).

SETTING UP A DEVICE FOR DEVELOPMENT

2. Enable USB debugging on your device.• On most devices running Android 3.2 or older, you can find the option

under Settings > Applications > Development.• On Android 4.0 and newer, it's in Settings > Developer options.

• Note: On Android 4.2 and newer, Developer options is hidden by default. To make it available, go to Settings > About phone and tap Build number seven times. Return to the previous screen to find Developer options.

SETTING UP A DEVICE FOR DEVELOPMENT

3. Set up your system to detect your device.• If you're developing on Windows, you need to install a USB driver for adb. For an installation guide and

links to OEM drivers, see the OEM USB Drivers document.

• Note: When you connect a device running Android 4.2.2 or higher to your computer, the system shows a dialog asking whether to accept an RSA key that allows debugging through this computer. This security mechanism protects user devices because it ensures that USB debugging and other adb commands cannot be executed unless you're able to unlock the device and acknowledge the dialog. This requires that you have adb version 1.0.31 (available with SDK Platform-tools r16.0.1 and higher) in order to debug on a device running Android 4.2.2 or higher.

SETTING UP A DEVICE FOR DEVELOPMENT

• When plugged in over USB, you can verify that your device is connected by executing adb devices from your SDK platform-tools/ directory. If connected, you'll see the device name listed as a "device."• If using Android Studio, run or debug your application as usual. You will be

presented with a Device Chooser dialog that lists the available emulator(s) and connected device(s). Select the device upon which you want to install and run the application.• If using the Android Debug Bridge (adb), you can issue commands with the

-d flag to target your connected device.

RUN ON A REAL DEVICE

Set up your device1. Plug in your device to your development machine with a USB cable. If you're developing

on Windows, you might need to install the appropriate USB driver for your device. 2. Enable USB debugging on your device.

• On most devices running Android 3.2 or older, you can find the option under Settings > Applications > Development.

• On Android 4.0 and newer, it's in Settings > Developer options.

• Note: On Android 4.2 and newer, Developer options is hidden by default. To make it available, go toSettings > About phone and tap Build number seven times. Return to the previous screen to find Developer options.

RUN THE APP FROM ANDROID STUDIO

1. Select one of your project's files and click Run from the toolbar.

2. In the Choose Device window that appears, select the Choose a running device radio button, select your device, and click OK .

• Android Studio installs the app on your connected device and starts it.

BUILDING AND RUNNING OVERVIEW

BUILDING AND RUNNING OVERVIEW

• The Android build process provides project and module build settings so that your Android modules are compiled and packaged into .apk files, the containers for your application binaries, based on your build settings. The apk file for each app contains all of the information necessary to run your application on a device or emulator, such as compiled .dex files (.class files converted to Dalvik byte code), a binary version of the AndroidManifest.xml file, compiled resources (resources.arsc) and uncompiled resource files for your application.

BUILDING AND RUNNING OVERVIEW

• To run an application on an emulator or device, the application must be signed using debug or release mode. You typically want to sign your application in debug mode when you develop and test your application, because the build system uses a debug key with a known password so you do not have to enter it every time you build. When you are ready to release the application to Google Play, you must sign the application in release mode, using your own private key.

BUILDING AND RUNNING OVERVIEW

• If you are using Android development tools, the build system can sign the application for you when build your app for debugging. You must obtain a certificate to sign your app when you build and app for release. For more information on signing applications, see Signing Your Applications.• The following diagram depicts the components involved in

building and running an application:

BUILDING AND RUNNING

BUILD SYSTEM OVERVIEW

BUILD SYSTEM OVERVIEW

The Android build system is the toolkit you use to build, test, run and package your apps. The build system can run as an integrated tool from the Android Studio menu and independently from the command line. You can use the features of the build system to:• Customize, configure, and extend the build process.• Create multiple APKs for your app with different features using the

same project and modules.• Reuse code and resources across source sets.

BUILD SYSTEM OVERVIEW

The flexibility of the Android build system enables you to achieve all of this without modifying your app's core source files. To build an Android Studio project, see Building and Running from Android Studio. To configure custom build settings in an Android Studio project, see Configuring Gradle Builds.

A DETAILED LOOK AT THE BUILD PROCESS

• The build process involves many tools and processes that generate intermediate files on the way to producing an .apk. If you are developing in Android Studio, the complete build process is done every time you run the Gradle build task for your project or modules. The build process is very flexible so it's useful, however, to understand what is happening under the hood since much of the build process is configurable and extensible. The following diagram depicts the different tools and processes that are involved in a build:

A DETAILED LOOK AT THE BUILD PROCESS

A DETAILED LOOK AT THE BUILD PROCESSThe general process for a typical build is outlined below. The build system merges all the resources from the configured product flavors, build types, and dependencies. If different folders contain resources with the same name or setting, the following override priority order is: dependencies override build types, which override product flavors, which override the main source directory.• The Android Asset Packaging Tool (aapt) takes your application resource files, such as the AndroidManifest.xml file and the

XML files for your Activities, and compiles them. An R.java is also produced so you can reference your resources from your Java code.

• The aidl tool converts any .aidl interfaces that you have into Java interfaces.• All of your Java code, including the R.java and .aidl files, are compiled by the Java compiler and .class files are output.• The dex tool converts the .class files to Dalvik byte code. Any 3rd party libraries and .class files that you have included in

your module build are also converted into .dex files so that they can be packaged into the final .apk file.• All non-compiled resources (such as images), compiled resources, and the .dex files are sent to the apkbuilder tool to be

packaged into an .apk file.• Once the .apk is built, it must be signed with either a debug or release key before it can be installed to a device.• Finally, if the application is being signed in release mode, you must align the .apk with the zipalign tool. Aligning the

final .apk decreases memory usage when the application is -running on a device.

A DETAILED LOOK AT THE BUILD PROCESS

Note: Apps are limited to a 64K method reference limit. If your app reaches this limit, the build process outputs the following error message:

To avoid this error, see Building Apps with Over 65K Methods.

Unable to execute dex: method ID not in [0, 0xffff]: 65536.

CONFIGURING GRADLE BUILDSTHIS SECTION BUILDS ON THE BUILD SYSTEM OVERVIEW AND BUILD AND RUNNING FROM ANDROID STUDIO TO SHOW YOU HOW TO USE BUILD VARIANTS BASED ON PRODUCT FLAVORS AND BUILD TYPES.

BUILD CONFIGURATION BASICS

• Android Studio projects contain a top-level build file and a build file for each module. The build files are called build.gradle, and they are plain text files that use Groovy syntax to configure the build with the elements provided by the Android plugin for Gradle. In most cases, you only need to edit the build files at the module level. For example, the build file for the app module in the BuildSystemExample project looks like this:

apply plugin: 'com.android.application'

android { compileSdkVersion 19 buildToolsVersion "19.0.0"

defaultConfig { minSdkVersion 8 targetSdkVersion 19 versionCode 1 versionName "1.0" } buildTypes { release { minifyEnabled true proguardFiles getDefaultProguardFile('proguard-android.txt'), 'proguard-rules.pro' } }}

dependencies { compile project(":lib") compile 'com.android.support:appcompat-v7:19.0.1' compile fileTree(dir: 'libs', include: ['*.jar'])}

BUILD CONFIGURATION BASICS

apply plugin: 'com.android.application' applies the Android plugin for Gradle to this build. This adds Android-specific build tasks to the top-level build tasks and makes the android {...} element available to specify Android-specific build options.android {...} configures all the Android-specific build options:• The compileSdkVersion property specifies the compilation target.• The buildToolsVersion property specifies what version of the build tools to use. To

install several versions of the build tools, use the SDK Manager.• Note: Always use a build tools version whose major revision number is higher or

equal to that of your compilation target and target SDK.

BUILD CONFIGURATION BASICS

• The defaultConfig element configures core settings and entries in the manifest file (AndroidManifest.xml) dynamically from the build system. The values in defaultConfig override those in the manifest file.• The configuration specified in the defaultConfig element applies to all build variants,

unless the configuration for a build variant overrides some of these values.• The buildTypes element controls how to build and package your app. By default, the

build system defines two build types: debug and release. The debug build type includes debugging symbols and is signed with the debug key. The release build type is not signed by default. In this example the build file configures the release version to use ProGuard.

Build Configuration Basics

BUILD CONFIGURATION BASICS

• The dependencies element is outside and after the android element. This element declares the dependencies for this module. Dependencies are covered in the following sections.

• Note: When you make changes to the build files in your project, Android Studio requires a project sync to import the build configuration changes. Click Sync Now on the yellow notification bar that appears for Android Studio to import the changes.

• Figure 1. Sync the project in Android Studio.

DECLEARE DEPENDENCIESThe app module in this example declares three dependencies: ...

dependencies { // Module dependency compile project(":lib")

// Remote binary dependency compile 'com.android.support:appcompat-v7:19.0.1'

// Local binary dependency compile fileTree(dir: 'libs', include: ['*.jar'])}

Each of these dependencies is described below. The build system adds all the compile dependencies to the compilation classpath and includes them in the final package.

MODULE DEPENDENCIES

The app module depends on the lib module, because MainActivity launches LibActivity1 as described in Open an Activity from a Library Module.

compile project(":lib") declares a dependency on the lib module of BuildSystemExample. When you build the app module, the build system assembles and includes the lib module.

REMOTE BINARY DEPENDENCIES

The app and lib modules both use the ActionBarActivity class from the Android Support Library, so these modules depend on it.

compile 'com.android.support:appcompat-v7:19.0.1' declares a dependency on version 19.0.1 of the Android Support Library by specifying its Maven coordinates. The Android Support Library is available in the Android Repository package of the Android SDK. If your SDK installation does not have this package, download and install it using the SDK Manager.

Android Studio configures projects to use the Maven Central Repository by default. (This configuration is included in the top-level build file for the project.)

LOCAL BINARY DEPENDENCIES

• Some modules do not use any binary dependencies from the local file system. If you have modules that require local binary dependencies, copy the JAR files for these dependencies into <moduleName>/libs inside your project.

• compile fileTree(dir: 'libs', include: ['*.jar']) tells the build system that any JAR file inside app/libs is a dependency and should be included in the compilation classpath and in the final package.

• For more information about dependencies in Gradle, see Dependency Management Basics in the Gradle User Guide.

RUN PROGUARDThe build system can run ProGuard to obfuscate your classes during the build process. In BuildSystemExample, modify the build file for the app module to run ProGuard for the release build:...

android { ... buildTypes { release { minifyEnabled true proguardFiles getDefaultProguardFile('proguard-android.txt'), 'proguard-rules.pro' } }}...

RUN PROGUARD

• getDefaultProguardFile('proguard-android.txt') obtains the default ProGuard settings from the Android SDK installation. Android Studio adds the module-specific rules file proguard-rules.pro at the root of the module, where you can add custom ProGuard rules.

APPLICATION ID FOR PACKAGE IDENTIFICATIONWith the Android build system, the applicationId attribute is used to uniquely identify application packages for publishing. The application ID is set in the android section of the build.gradle file.apply plugin: 'com.android.application'

android { compileSdkVersion 19 buildToolsVersion "19.1"

defaultConfig { applicationId "com.example.my.app" minSdkVersion 15 targetSdkVersion 19 versionCode 1 versionName "1.0" } ...

APPLICATION ID FOR PACKAGE IDENTIFICATION• Note: The applicationId is specified only in your build.gradle

file, and not in the AndroidManifest.xml file.

• When using build variants, the build system enables you to uniquely identify different packages for each product flavors and build types. The application ID in the build type is added as a suffix to those specified for the product flavors.

APPLICATION ID FOR PACKAGE IDENTIFICATION productFlavors { pro { applicationId = "com.example.my.pkg.pro" } free { applicationId = "com.example.my.pkg.free" } }

buildTypes { debug { applicationIdSuffix ".debug" } } ....

APPLICATION ID FOR PACKAGE IDENTIFICATION• The package name must still be specified in the manifest file. It is used in your source code

to refer to your R class and to resolve any relative activity/service registrations.package="com.example.app"> • Note: If you have multiple manifests (for example, a product flavor specific manifest and a

build type manifest), the package name is optional in those manifests. If it is specified in those manifests, the package name must be identical to the package name specified in the manifest in the src/main/ folder.

• For more information about the build files and process, see Build System Overview.