By default, there are two build types to build your application using the Gradle build settings: - one for debugging your application — debug — and one for building your - final package for release — release mode. Regardless of which build type - your modules use, the app must be signed before it can install on an emulator or device—with - a debug key when building in debug mode and with your own private key when building in release mode.
- -Whether you're building with the debug or release build type, you need to run
- and build your module. This will create the .apk file that you can install on an emulator or device.
- When you build using the debug build type, the .apk file is automatically signed by the SDK tools
- with a debug key based on the debuggable true setting in the module's build.gradle file,
- so it's instantly ready for installation onto an emulator or attached
- development device. You cannot distribute an application that is signed with a debug key.
- When you build using the release build type, the .apk file is unsigned, so you
- must manually sign it with your own private key, using Keytool and Jarsigner settings in the
- module's build.gradle file.
It's important that you read and understand Signing Your Applications, particularly once - you're ready to release your application and share it with end-users. That document describes the - procedure for generating a private key and then using it to sign your APK file. If you're just - getting started, however, you can quickly run your applications on an emulator or your own - development device by building in debug mode.
- -If you don't have Gradle, you can obtain it from the Gradle - home page. Install it and make sure it is in your executable PATH. Before calling Gradle, you - need to declare the JAVA_HOME environment variable to specify the path to where the JDK is - installed.
- -Note: When using ant and installing JDK on Windows,
- the default is to install in the "Program Files" directory. This location will cause
- ant to fail, because of the space. To fix the problem, you can specify the JAVA_HOME
- variable like this:
-
set JAVA_HOME=c:\Progra~1\Java\<jdkdir>- -
The easiest solution, however, is to install JDK in a non-space directory, for example:
- -c:\java\jdk1.7- -
For immediate application testing and debugging, you can build your application in debug mode - and immediately install it on an emulator. In debug mode, the build tools automatically sign your - application with a debug key and optimize the package with {@code zipalign}.
- -To build in debug mode, open a command-line and navigate to the root of your project directory.
- Use Gradle to build your project in debug mode, invoke the assembleDebug build task
- using the Gradle wrapper script (gradlew assembleRelease).
-
-
This creates your debug .apk file inside the module build/
- directory, named <your_module_name>-debug.apk. The file is already signed
- with the debug key and has been aligned with
- zipalign.
On Windows platforms, type this command:
- --> gradlew.bat assembleDebug -- -
On Mac OS and Linux platforms, type these commands:
- --$ chmod +x gradlew -$ ./gradlew assembleDebug -- -
The first command (chmod) adds the execution permission to the Gradle wrapper
- script and is only necessary the first time you build this project from the command line.
After you build the project, the output APK for the app module is located in
- app/build/outputs/apk/, and the output AAR for any lib modules is located in
- lib/build/outputs/libs/.
To see a list of all available build tasks for your project, type this command:
- --$ ./gradlew tasks -- -
Each time you change a source file or resource, you must run Gradle again in order to package up - the latest version of the application.
- -To install and run your application on an emulator, see the section about Running on the Emulator.
- -When you're ready to release and distribute your application to end-users, you must build your - application in release mode. Once you have built in release mode, it's a good idea to perform - additional testing and debugging with the final .apk.
- -Before you start building your application in release mode, be aware that you must sign the - resulting application package with your private key, and should then align it using the {@code - zipalign} tool. There are two approaches to building in release mode: build an unsigned package - in release mode and then manually sign and align the package, or allow the build script to sign - and align the package for you.
- -If you build your application unsigned, then you will need to manually sign and align - the package.
- -To build an unsigned .apk in release mode, open a command-line and navigate to the
- root of your module directory. Invoke the assembleRelease build task.
-
-
On Windows platforms, type this command:
- --> gradlew.bat assembleRelease -- -
On Mac OS and Linux platforms, type this command:
- --$ ./gradlew assembleRelease -- - -
This creates your Android application .apk file inside the project bin/
- directory, named <your_module_name>-unsigned.apk.
Note: The .apk file is unsigned at this point and can't - be installed until signed with your private key.
- -Once you have created the unsigned .apk, your next step is to sign the .apk with your private - key and then align it with {@code zipalign}. To complete this procedure, read Signing Your Applications.
- -When your .apk has been signed and aligned, it's ready to be distributed to end-users.
- You should test the final build on different devices or AVDs to ensure that it
- runs properly on different platforms.
If you would like, you can configure the Android build script to automatically sign and align - your application package. To do so, you must provide the path to your keystore and the name of - your key alias in your modules's build.gradle file. With this information provided, - the build will prompt you for your keystore and alias password when you build using the release - build type and produce your final application package, which will be ready for distribution.
- -To specify your keystore and alias, open the module build.gradle file (found in - the root of the module directory) and add entries for {@code storeFile}, {@code storePassword}, - {@code keyAlias} and {@code keyPassword}. - For example:
-
-storeFile file("myreleasekey.keystore")
-keyAlias "MyReleaseKey"
-
-
- Save your changes. Now you can build a signed .apk in release mode:
- -
-...
-android {
- ...
- defaultConfig { ... }
- signingConfigs {
- release {
- storeFile file("myreleasekey.keystore")
- storePassword "password"
- keyAlias "MyReleaseKey"
- keyPassword "password"
- }
- }
- buildTypes {
- release {
- ...
- signingConfig signingConfigs.release
- }
- }
-}
-...
-
- Caution: As described above, your password will be - visible on the screen.
-This creates your Android application .apk file inside the module build/
- directory, named <your_module_name>-release.apk. This .apk file has
- been signed with the private key specified in build.gradle file and aligned with {@code
- zipalign}. It's ready for installation and distribution.
Once you have signed your application with a private key, you can install and run it on an - emulator or device. You can - also try installing it onto a device from a web server. Simply upload the signed .apk to a web - site, then load the .apk URL in your Android web browser to download the application and begin - installation. (On your device, be sure you have enabled - Settings > Applications > Unknown sources.)
- -Before you can run your application on the Android Emulator, you must create an AVD.
- -To run your application:
- -From your SDK's platform-tools/ directory, execute the {@code android} tool
-with the avd options:
-android avd -- -
In the Virtual Devices view, select an AVD and click Start.
-From your SDK's tools/ directory, install the {@code .apk} on the
- emulator:
-adb install <path_to_your_bin>.apk -- -
Your .apk file (signed with either a release or debug key) is in your module {@code build/} - directory after you build your application.
- -If there is more than one emulator running, you must specify the emulator upon which to
- install the application, by its serial number, with the -s option. For
- example:
-adb -s emulator-5554 install path/to/your/app.apk -- -
To see a list of available device serial numbers, execute {@code adb devices}.
-If you don't see your application on the emulator, try closing the emulator and launching the - virtual device again from the AVD Manager. Sometimes when you install an application for the - first time, it won't show up in the application launcher or be accessible by other applications. - This is because the package manager usually examines manifests completely only on emulator - startup.
- -Be certain to create multiple AVDs upon which to test your application. You should have one - AVD for each platform and screen type with which your application is compatible. For instance, if - your application compiles against the Android 4.0 (API Level 14) platform, you should create an - AVD for each platform equal to and greater than 4.0 and an AVD for each screen type you support, then test your - application on each one.
- -Tip: If you have only one emulator running, you can
- build your application and install it on the emulator in one simple step. Navigate to the root of
- your project directory and use Ant to compile the project with install mode: ant
- install. This will build your application, sign it with the debug key, and install it on
- the currently running emulator.
Before you can run your application on a device, you must perform some basic setup for your - device:
- -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.
-Read Setting up a Device for - Development for more information.
- -Once your device is set up and connected via USB, navigate to your SDK's platform-tools/
- directory and install the .apk on the device:
-adb -d install path/to/your/app.apk -- -
The {@code -d} flag specifies that you want to use the attached device (in case you also have - an emulator running).
- -For more information on the tools used above, please see the following documents:
- -As you begin developing Android applications, understand that all Android applications must be - digitally signed before the system will install them on an emulator or device. There are two ways - to do this: with a debug key (for immediate testing on an emulator or development - device) or with a private key (for application distribution).
- -The Android build tools help you get started by automatically signing your .apk files with a - debug key at build time. This means that you can build your application and install it on the - emulator without having to generate your own private key. However, please note that if you intend - to publish your application, you must sign the application with your own private - key, rather than the debug key generated by the SDK tools.
- -Please read Signing Your - Applications, which provides a thorough guide to application signing on Android and what it - means to you as an Android application developer. The document also includes a guide to publishing - and signing your application.
- -The Android build system uses the Android plugin for Gradle to support the Gradle Domain - Specific Language (DSL) and declarative language elements. See the - Android Plug-in for Gradle section for - a description of the plugin and a link to the complete list of the supported Gradle DSL elements.
- - - diff --git a/docs/html/tools/building/building-studio.jd b/docs/html/tools/building/building-studio.jd deleted file mode 100644 index 2b18b6673885c880034b65c70b6d0a7284207f06..0000000000000000000000000000000000000000 --- a/docs/html/tools/building/building-studio.jd +++ /dev/null @@ -1,801 +0,0 @@ -page.title=Building and Running from Android Studio -parent.title=Building and Running -parent.link=index.html -@jd:body - -- By default, Android Studio sets up new projects to deploy to the Emulator or - a physical device with just a few clicks. With Instant Run, you can push - changes to methods and existing app resources to a running app without - building a new APK, so code changes are visible almost instantly. -
- -
- To build and run your app, click Run 'app' . Android Studio builds your app with
- Gradle, asks you to select a deployment target (an emulator or a connected
- device), and then deploys your app to it. You can customize some of this
- default behavior, such as selecting an automatic deployment target, by
- changing the run configuration.
-
- If you want to use the Android - Emulator to run your app, you need to have an Android Virtual Device - (AVD) ready. If you haven't already created one, then after you click - Run 'app', click Create New Emulator in the - Select Deployment Target dialog. Follow the Virtual Device - Configuration wizard to define the type of device you want to emulate. For - more information, see Managing AVDs with the AVD - Manager. -
- -- If you're using a physical Android device, you need to enable USB debugging - on the device. For more information, see Using Hardware Devices. -
- -
- Note: You can also deploy your app in debug mode by clicking
- Debug 'app' . Running your app in debug mode
- allows you to set breakpoints in your code, examine variables and evaluate
- expressions at run time, and run debugging tools. To learn more, read about
- Debugging with
- Android Studio.
-
- The run configuration specifies the module to run, package to deploy, - activity to start, target device, emulator settings, and Logcat options. The - default run configuration launches the default project activity and uses the - Device Chooser for target device selection. If the default - settings don't suit your project or module, you can customize the run - configuration, or even create a new one, at the project, default, and module - levels. To edit a run configuration: -
- -- By default, Android Studio builds the debug version of your app, which is - intended only for testing, when you click Run 'app'. You - need to build the release version when preparing your app for public - release. -
-- To change the build variant Android Studio uses, go to Build - > Select Build Variant and select a different one from - the drop-down menu. By default, new projects are set up with a debug and - release build variant. -
- -- Using product flavors, you can create additional build variants for - different versions of your app, each having different features or device - requirements. To learn more about build variants and product flavors, read - Configuring Gradle - Builds. -
- -
- You can view details about the build process by clicking Gradle
- Console 
. The console displays each
- task that Gradle executes in order to build your app, as shown in figure 1.
-
-- Figure 1. The Gradle Console in Android Studio. -
- -
- If your build variants use product flavors, Gradle also invokes tasks to
- build those product flavors. To view the list of all available build tasks,
- click Gradle on the right side of the IDE
- window.
-
- If an error occurs during the build process, the Messages window
- appears to describe the issue. Gradle may recommend some command-line
- options to help you resolve the issue, such as --stacktrace or
- --debug. To use command-line options with your build process:
-
- Gradle will apply these command-line options the next time you try building - your app. -
- -- When you click Run 'app', Android Studio generates a debug - APK and deploys it to your target device. Before you can generate a release - version of your app for public distribution, however, you must first learn - how to sign your - app. You can then generate multiple signed APKs of your debug or release - build variants. To locate the generated APK files, click the link in the - pop-up dialog, as shown in figure 2. -
- -
- 
-
- Figure 2. Click the link to locate the generated APK - files. -
- -
- Introduced in Android Studio 2.0, Instant Run is a behavior for the
- Run 
and Debug commands that significantly reduces the
- time between updates to your app. Although your first build may take longer
- to complete, Instant Run pushes subsequent updates to your app without
- building a new APK, so changes are visible much more quickly.
-
- Instant Run is supported only when you deploy the debug build variant, use
- Android Plugin for Gradle version 2.0.0 or higher, and set
- minSdkVersion to 15 or higher in your app's module-level
- build.gradle file. For the best performance, set
- minSdkVersion to 21 or higher.
-
- After deploying an app, a small, yellow thunderbolt icon appears within the
- Run button (or Debug
-
button), indicating that Instant Run is
- ready to push updates the next time you click the button. Instead of building
- a new APK, it pushes just those new changes and, in some cases, the app
- doesn't even need to restart but immediately shows the effect of those code
- changes.
-
- Instant Run pushes updated code and resources to your connected device or - emulator by performing a hot swap, warm swap, or cold - swap. It automatically determines the type of swap to perform based on - the type of change you made. The following table describes how Instant Run - behaves when you push certain code changes to a target device. -
- -| - Code Change - | -- Instant Run Behavior - | -
|---|---|
-
|
-
- - Supported with hot swap: This is the - fastest type of swap and makes changes visible much more quickly. Your - application keeps running and a stub method with the new implementation is used - the next time the method is called. - - -- Hot swaps do not re-initialize objects in your running app. You may need to - restart the current activity, or restart the app, before - you see certain updates. By default, Android Studio automatically restarts the - current activity after performing a hot swap. If you do not want this behavior, - you can disable automatic activity restarts. - - |
-
-
|
- - Supported with warm swap: This swap - is still very fast, but Instant Run must restart the current activity when it - pushes the changed resources to your app. Your app keeps running, but a small - flicker may appear on the screen as the activity restarts—this is normal. - | -
- Structural code changes, such as:
-
|
-
- - Supported with cold swap (API level 21 or higher): This swap - is a bit slower because, although a new APK is not required, Instant Run must - restart the whole app when it pushes structural code changes. - - -- For target devices running API level 20 or lower, Android Studio - deploys a full APK. - - |
-
-
|
-
- - When making changes to the app's manifest or resources referenced by the - manifest, Android Studio automatically deploys a new build - in order to apply these changes. This is because certain information about - the app, such as its name, app icon resources, and intent filters, are - determined from the manifest when the APK is installed on the device. - - -
- If your build process automatically updates any part of the app manifest,
- such as automatically iterating - When updating an Android widget UI element, you need to perform a Clean and Rerun to see your changes. Alternatively, because - performing clean builds may take longer while using Instant Run, you can - temporarily disable Instant Run while making - updates to your widget UI. - - |
-
- Note: If you need to restart your app after a crash, do not
- launch it from your target device. Restarting your app from your target
- device does not apply any of your code changes since the last cold swap or
- incremental build. To launch your app with all your recent changes,
- click Run (or Debug
- 
) from Android Studio.
-
- When pushing code changes that affect certain initializers, such as changes
- to an app's {@link android.app.Application#onCreate onCreate()} method, you
- need to restart your app for the changes to take effect. To perform an
- incremental build and restart the app, click Rerun
- 
.
-
- If you need to deploy a clean build, select Run
- > Clean and Rerun 'app' from the main menu, or hold down the
- Shift key while clicking Rerun
. This action stops the running app,
- performs a full clean build, and deploys the new APK to your target device.
-
- When performing a hot swap, your app keeps running but Android Studio - automatically restarts the current activity. To disable this default setting: -
- -- If automatic activity restart is disabled, you can manually restart the current - activity from the menu bar by selecting Run > Restart - Activity. -
- -- Android Studio enables Instant Run by default for projects built using - Android Plugin for Gradle 2.0.0 and higher. -
- -- To update an existing project with the latest version of the plugin: -
- -- Navigate to Build, Execution, Deployment > - Instant Run and click Update Project, - as shown in figure 3. -
- -- If the option to update the project does not appear, it’s already - up-to-date with the latest Android Plugin for Gradle. -
- -
-
- - Figure 3. Updating the Android Plugin for Gradle for an - existing project. -
-- You also need to change the build variant to - a debug version of your app to start using Instant Run. -
- -
- When you deploy a clean build, Android Studio instruments your app to allow
- Instant Run to push code and resource updates. Although updating the running
- app happens much more quickly, the first build may take longer to complete.
- You can improve the build process by configuring a few
- DexOptions settings:
-
maxProcessCount
- gradlew --stop
- ./gradlew --stop
- javaMaxHeapSize
-
- The following example sets maxProcessCount to 4 and
- javaMaxHeapSize to "2g" in the module-level
- build.gradle file:
-
-android {
- ...
- dexOptions {
- maxProcessCount 4 // this is the default value
- javaMaxHeapSize "2g"
- }
-}
-
-
-- You should experiment with these settings by incrementing their values and - observing the effect on your build times. You could experience a negative - impact to performance if you allocate too many resources to the dexing process. -
- -- Android - Plugin for Gradle version 2.1.0 and higher features additional build - process improvements, including incremental Java compilation and - dexing-in-process. Incremental Java compilation is enabled by default and - reduces compilation time during development by only recompiling portions of - the source that have changed or need to be recompiled. -
- -
- Dexing-in-process performs dexing within the build process rather than in a
- separate, external VM processes. This not only makes incremental builds much
- faster, but also significantly speeds up full builds. To enable this feature,
- you need to set the Gradle daemon's maximum heap size to at least 2048 MB. You
- can do this by including the following in your project's
- gradle.properties file:
-
-
-org.gradle.jvmargs = -Xmx2048m -- - - -
- If you have defined a value for
- javaMaxHeapSize in your module-level build.gradle
- file, you need to set the daemon's max heap size to the value of
- javaMaxHeapSize + 1024 MB. For example, if you have set
- javaMaxHeapSize to "2g", you need to add the following to your
- project's gradle.properties file:
-
-
-org.gradle.jvmargs = -Xmx3072m -- - - -
- On Windows systems, Windows Defender may cause slowdowns while using Instant - Run. If you are using Windows Defender, you should - exclude your Android Studio project folder from Windows Defender malware - scans. -
- -- Using Crashlytics is known to cause slower build times. To improve build - performance while developing your app, you can - disable Crashlytics for your debug build variant. -
- -- Instant Run is designed to speed up the build and deploy process in most - situations. However, there are some aspects to using Instant Run that might - affect its behavior and compatibility with your app. If you experience any - other issues while using Instant Run, please file a bug. -
- -- Instant Run uses different techniques to perform hot, warm, and cold swaps - that are specific to the API level of the target device. For this reason, - while deploying an app to multiple devices at once, Android Studio - temporarily turns off Instant Run. -
- -
- If your project is configured for Legacy Multidex—that
- is, when build.gradle is configured with multiDexEnabled
- true and minSdkVersion 20 or lower—and you deploy to
- target devices running Android 4.4 (API level 20) or lower, Android Studio
- disables Instant Run.
-
- If minSdkVersion is set to 21 or higher, Instant Run
- automatically configures your app for multidex. Because Instant Run only
- works with the debug version of your app, you may need to configure your app for
- multidex when deploying your release build variant.
-
- Instrumented tests load both the debug APK and a test APK into the same - process on a test device, allowing control methods to override the normal - lifecycle of the app and perform tests. While running or debugging - instrumented tests, Android Studio does not inject the additional methods - required for Instant Run and turns the feature off. -
- -- While profiling an app, you should disable Instant Run. There is a small - performance impact when using Instant Run and a slightly larger impact when - overriding methods with a hot swap. This performance impact could interfere - with information provided by performance profiling tools. Additionally, the - stub methods generated with each hot swap can complicate stack traces. -
- -- Android Studio temporarily disables the Java Code Coverage Library (JaCoCo) - and ProGuard while using Instant Run. Because Instant Run only works with - debug builds, this does not affect your release build. -
- -- Certain third-party plugins that perform bytecode enhancement may cause - issues with how Instant Run instruments your app. If you experience these - issues, but want to continue using Instant Run, you should disable those - plugins for your debug build variant. You can also help improve compatibility - with third-party plugins by filing a bug. -
- -- Instant Run only instruments your app's main process in order to perform hot - swaps and warm swaps. When pushing code changes to other app processes, such - as changes to a method implementation or an existing resource, Instant Run - performs a cold swap. -
- -- To disable Instant Run: -
- -This 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.
- - -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'])
-}
-
-
-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:
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.
-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.
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.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.
- -The 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.
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.
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.
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.
- -The 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'
- }
- }
-}
-...
-
-
-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.
With 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"
- }
- ...
-
-
-Note: The applicationId is specified only in your -{@code 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.
- -
- productFlavors {
- pro {
- applicationId = "com.example.my.pkg.pro"
- }
- free {
- applicationId = "com.example.my.pkg.free"
- }
- }
-
- buildTypes {
- debug {
- applicationIdSuffix ".debug"
- }
- }
- ....
-
-
-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.
- - - -The debug and the release versions of the app differ on whether the application can be -debugged on secure devices and on how the APK is signed. The build system signs the debug -version with a default key and certificate using known credentials to avoid a password prompt at -build time. The build system does not sign the release version unless you explicitly define a -signing configuration for this build. If you do not have a release key, you can generate one as -described in Signing your Applications.
- - -This section describes how the build system can help you create different versions of the same -application from a single project. This is useful when you have a demo version and a paid version -of your app, or if you want to distribute multiple APKs for different device configurations on -Google Play.
- -The build system uses product flavors to create different product versions of your app. -Each product version of your app can have different features or device requirements. The build -system also uses build types to apply different build and packaging settings to each product version. -Each product flavor and build type combination forms a build variant. The build system generates a -different APK for each build variant of your app.
- -This example project consists of the two default build types (debug and release) -and two product flavors for app type (demo and full). For more information on advanced uses of -build variants, see - Build System Overview .
- - -To create different product versions of your app:
- -The rest of this section walks you through these steps in detail using a
-BuildSystemExample project. You create two flavors of the
-BuildSystemExample app, a demo flavor and a full flavor. Both flavors share
-MainActivity, to which you add a new button to launch a new activity,
-SecondActivity. This new activity is different for each flavor, so you simulate a
-situation where the new activity would have more features in the full flavor than in the demo
-flavor. At the end of the exercise, you end up with two different APKs, one for each flavor.
To define two product flavors, edit the build file for the app module to add the following -configuration:
- -
-...
-android {
- ...
- defaultConfig { ... }
- signingConfigs { ... }
- buildTypes { ... }
- productFlavors {
- demo {
- applicationId "com.buildsystemexample.app.demo"
- versionName "1.0-demo"
- }
- full {
- applicationId "com.buildsystemexample.app.full"
- versionName "1.0-full"
- }
- }
-}
-...
-
-
-The product flavor definitions support the same properties as the defaultConfig
-element. The base configuration for all flavors is specified in defaultConfig, and each
-flavor overrides any default values. The build file above uses the applicationId
-property to assign a different package name to each flavor: since each flavor definition creates a
-different app, they each need a distinct package name.
Note: To distribute your app using
-Multiple APK Support in
-Google Play, assign the same package name to all variants and give each variant a different
-versionCode. To distribute different variants of your app as separate apps in Google
-Play, assign a different package name to each variant.
Now you create source folders and add a SecondActivity to each flavor. To create
-the source directory structure for the demo flavor:
Similarly, create the following directories:
-app/src/demo/javaapp/src/demo/resapp/src/demo/res/layoutapp/src/demo/res/valuesThe resulting directory structure looks like figure 1.
- -
-Figure 1. New source directories for the demo flavor.
- -To add SecondActivity to the demo flavor:
To add the layout for SecondActivity and a strings resource to the demo flavor:
OK.Replace the contents of the new copy of strings.xml with the
- following:
-<?xml version="1.0" encoding="utf-8"?> -<resources> - <string name="hello_world">Demo version only.</string> -</resources> --
Now you add source folders and SecondActivity to the full flavor by making a copy
-of the demo flavor:
Replace the contents of strings.xml under src/full/res/values - with the following:
--<?xml version="1.0" encoding="utf-8"?> -<resources> - <string name="hello_world">This is the full version!</string> -</resources> --
Note: From this point on, you could develop
-SecondActivity independently inside each
-flavor. For example, you could add more features to this activity in the full flavor.
To work on files from a particular flavor, click on Build Variants on the left -of the IDE window and select the flavor you want to modify in the Build Variants panel, -as shown in figure 2. Android Studio may show errors in source files from flavors other than the -one selected in the Build Variants panel, but this does not affect the outcome of the -build.
- -
-Figure 2. The Build Variants panel.
- -Since the flavor-specific activity (SecondActivity) has the same package name and
-activity name in both flavors, you can launch it from the main activity, which is common to all
-flavors. To modify the main activity:
Edit activity_main.xml and add a new button to
- MainActivity:
-<LinearLayout ...> - ... - <Button - android:id="@+id/button2" - android:layout_width="wrap_content" - android:layout_height="wrap_content" - android:text="@string/button2" - android:onClick="onButton2Clicked"/> -</LinearLayout> --
onButton2Clicked method to
- MainActivity.Add the following code to the onButton2Clicked method of
- MainActivity:
-public void onButton2Clicked(View view) {
- Intent intent = new Intent(this, SecondActivity.class);
- startActivity(intent);
-}
-
- Edit the app's manifest to include a reference to SecondActivity:
-<manifest ...> - <application ...> - ... - <activity - android:name="com.buildsystemexample.app.SecondActivity" - android:label="@string/title_activity_second" > - </activity> - </application> -</manifest> --
Build types represent the build packaging versions generated for each app package. By default, -the debug and release build types are provided. -
- -
-...
-android {
- ...
- defaultConfig { ... }
- signingConfigs { ... }
- buildTypes { ... }
- productFlavors {...}
- buildTypes {
- release {
- minifyEnabled false
- proguardFiles getDefaultProguardFile('proguard-android.txt'), 'proguard-rules.pro'
- }
- debug {
- debuggable true
- }
- }
-}
-...
-
-
-Note: Although only the release build type appears in -the default build.gradle file, both the release and debug build types are -applied to each build.
- -In this example, the product flavors and build types create the following build variants: -
To build this example, click the Build menu option in Android Studio or invoke
-the assemble task from the command line.
Note: The Build > Make Project option compiles -all the source files in the entire project that have been modified since the last compilation. The -Build > Rebuild Project option recomplies all the source files in the project.
- -Separate output folders are created for each build variant.
diff --git a/docs/html/tools/building/index.jd b/docs/html/tools/building/index.jd deleted file mode 100644 index b5a56c0c9a4ca5c90a18cd30e6dd1a38d26c4ef4..0000000000000000000000000000000000000000 --- a/docs/html/tools/building/index.jd +++ /dev/null @@ -1,40 +0,0 @@ -page.title=Building and Running Overview -@jd:body - -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.
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.
- -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:
- -
diff --git a/docs/html/tools/building/manifest-merge.jd b/docs/html/tools/building/manifest-merge.jd
deleted file mode 100644
index 225358433af650efcb64d92eea29853389b2e761..0000000000000000000000000000000000000000
--- a/docs/html/tools/building/manifest-merge.jd
+++ /dev/null
@@ -1,515 +0,0 @@
-page.title=Manifest Merging
-@jd:body
-
-With Android Studio and Gradle-based builds, each app can
-contain manifest files in multiple locations, such as the src/main/ folder for
-the productFlavor, libraries, Android ARchive (AAR) bundles of Android Library
-projects, and dependencies. During the build process, manifest merging combines the settings from
-the various AndroidManifest.xml files included in your app into a single, generated APK
-manifest file for app packaging and distribution. Manifest settings are merged based on the manifest
-priority, determined by the manifest's file location. Building your app merges the
-manifest elements, attributes, and sub-elements from these manifests for the specified
-build variant.
Merge conflicts occur when merged manifests contain the same manifest element but with a
-different attribute value that does not resolve based on the default merge conflict rules.
-Conflict markers and selectors can also define custom merge rules,
-such as allowing an imported library to have a minSdkVersion higher than the
-version defined in the other higher priority manifests.
The manifest merge priority determines which manifest settings are retained in merge conflicts, -with the settings in higher priority manifest overwriting those in lower priority manifests. -The following list details which manifest settings are are the highest priority during the merge -process:
- -buildType manifest settings productFlavor manifest settings src/main/ directory of an app projectManifest merge conflicts are resolved at the XML node and -attribute levels based on the following merge rules.
- -| High Priority Element | -Low Priority Element | -Manifest Merge Result | -
|---|---|---|
| no attribute | -no attribute | -no attribute | -
| attribute set to default | -default attribute | -|
| attribute set to non-default | -low priority attribute | -|
| attribute set to default | -no attribute | -default attribute | -
| attribute set to non-default | - -high priority attribute | -|
| attribute set to default | -attribute set to default | -default attribute | -
| attribute set to default | -attribute set to non-default | -low priority attribute | -
| attribute set to non-default | -attribute set to default | -high priority attribute | -
| attribute set to non-default | -attribute set to non-default | -Merge if settings match, otherwise causes conflict error. | -
Exceptions to the manifest merge rules:
- -uses-feature android:required; and
- uses-library android:required elements default to true and use
- an OR merge so that any required feature or library is included in the generated APK. <uses-sdk>
- elements, minSdkVersion and
- targetSdkVersion, default to a value of 1. When
- merge conflicts occur, the value in the higher priority manifest version is used.minSdkVersion value higher than the app's
- src/main/ manifest manifest generates an error unless
- the overrideLibrary conflict marker is used.
-
- Note: If not explicitly declared, the targetSdkVersion
- defaults to the minSdkVersion value. When no build.gradle file, the
- minSdkVersion defaults to 1.
targetSdkVersion value lower than the app's
- src/main/ manifest, the manifest merge
- process explicitly grants permissions and ensures that the imported library functions properly. manifest element only merges with child manifest elements. intent-filter element is never changed and is always added to the common
- parent node in the merged manifest. Important: After the manifests are merged, the build process
-overrides the final manifest settings with any settings that are also in the
-build.gradle file. For more details, see
-Configuring Gradle Builds.
Manifest markers and selectors override the default merge rules through
-specific conflict resolutions. For example, use a conflict marker to
-merge a library manifest with a higher minSdkVersion value than the higher priority
-manifest, or to merge manifests with the same activity but different android:theme
-values.
A merge conflict marker is a special attribute in the Android tools namespace that defines a -specific merge conflict resolution. Create a conflict marker to avoid a merge conflict error for -conflicts not resolved by the default merge rules. Supported merge conflict markers include:
- -mergereplacestrictmerge-onlyremoveremove-AllBy default, the manifest merge process applies the merge conflict marker to
-the node level. All declared manifest attributes default to a strict
-merging policy.
To set a merge conflict marker, first declare the namespace in the
-AndroidManifest.xml file. Then, enter the merge conflict marker in the manifest to
-specify a custom merge conflict action. This example inserts the replace marker to
-set a replace action to resolve conflicts between the android:icon and
-android:label manifest elements.
- -<manifest xmlns:android="http://schemas.android.com/apk/res/android" - package="com.android.tests.flavorlib.app" - xmlns:tools="http://schemas.android.com/tools"> - - <application - android:icon="@drawable/icon" - android:label="@string/app_name" - tools:replace="icon, label"> - ... - - - -- - -
Conflict markers use tools:node and tools:attr attributes to
-restrict merge actions at the XML node or attribute level.
The tools:attr markers use only the restrict, remove, and
-replace merge actions. Multiple tools:attr marker values can be applied
-to a specific element. For example, use tools:replace="icon, label, theme" to replace
-lower priority icon, label, and theme attributes.
The overrideLibrary conflict marker applies to the <uses-sdk>
-manifest declaration and is used to import a library even though the library's
-<uses-sdk> values, such as minSdkVersion
-are set to different values than those in the other higher priority manifests.
Without this marker, library manifest merge conflicts from the
-<uses-sdk> values cause the merge process to fail.
This example applies the overrideLibrary conflict marker to resolve the merge
-conflict between minSdkVersion values in the src/main/ manifest and an
-imported library manifest.
-
-
-
src/main/ manifest:
-<manifest xmlns:android="http://schemas.android.com/apk/res/android" - package="com.android.example.app" - xmlns:tools="http://schemas.android.com/tools"> - ... - <uses-sdk android:targetSdkVersion="22" android:minSdkVersion="2" - tools:overrideLibrary="com.example.lib1, com.example.lib2"/> - ... -- -
Library manifest:
- --<manifest xmlns:android="http://schemas.android.com/apk/res/android" - package="com.example.lib1"> - ... - <uses-sdk android:minSdkVersion="4" /> - ... - </manifest> -- -
Note: The default merge process does not allow importing a library
-with a higher minSdkVersion than the app's src/main/ manifest unless
-the overrideLibrary conflict marker is used.
Marker selectors limit a merge action to a specific lower priority manifest. For example, a -marker selector can be used to remove a permission from only one library, while allowing the -same permission from other libraries.
- -This example uses the tools:node marker to remove the permisionOne
-attribute, while the tools:selector selector specifies the specific library as
-com.example.lib1. The permisionOne permission is filtered from only the
-lib1 library manifests.
-<manifest xmlns:android="http://schemas.android.com/apk/res/android" - package="com.android.example.app" - xmlns:tools="http://schemas.android.com/tools"> - ... - <permission - android:name="permissionOne" - tools:node="remove" - tools:selector="com.example.lib1"> - ... -- - - -
Manifest merging can also be configured to use manifest placeholders to inject
-property values from the build.gradle file into the manifest attributes.
Manifest placeholders use the syntax ${name} for attribute values, where
-name is the injected build.gradle property. The build.gradle
-file uses the manifestPlaceholders property to define the placeholder values.
Note: Unresolved placeholder names in apps cause build failures. -Unresolved placeholder names in libraries generate warnings and need to be resolved when importing -the library into an app.
- -This example shows the manifest placeholder ${applicationId} used to inject the
-build.gradle applicationId property value in to android:name
-attribute value.
Note: Android Studio provides a default
-${applicationId} placeholder for the build.gradle
-applicationId value that is not shown in the build file.
-When building an AAR (Android ARchive) package for library modules, do not provide an
-automatic @{applicationId} placeholder in the
-manifest merge settings.
-Instead, use a different placeholder, such as @{libApplicationId} and
-provide a value for it if you want to include application Ids in the archive library.
Manifest entry:
- -
-
-<activity
-android:name=".Main">
- <intent-filter>
- <action android:name="${applicationId}.foo">
- </action>
-</intent-filter>
-</activity>
-
-
-
-
-Gradle build file:
- -
-android {
- compileSdkVersion 22
- buildToolsVersion "22.0.1"
-
- productFlavors {
- flavor1 {
- applicationId = "com.mycompany.myapplication.productFlavor1"
- }
-}
-
-
-
-Merged manifest value:
- --<action android:name="com.mycompany.myapplication.productFlavor1.foo"> -- - -
The manifest placeholder syntax and build file manifestPlaceholders
-property can be used to inject other manifest values. For properties other than the
-applicationId, the manifestPlaceholders property is explicitly declared
-in the build.gradle file. This example shows the manifest placeholder for injecting
-activityLabel values.
Gradle build file:
- -
-android {
- defaultConfig {
- manifestPlaceholders = [ activityLabel:"defaultName"]
- }
- productFlavors {
- free {
- }
- pro {
- manifestPlaceholders = [ activityLabel:"proName" ]
- }
- }
-
-
-
-Placeholder in the manifest file:
- -
-<activity android:name=".MainActivity" android:label="${activityLabel}" >
-
-
-Note: The placeholder value supports partial value injection,
-for example android:authority="com.acme.${localApplicationId}.foo".
When using the GroupableProductFlavor property, the manifest merge
-priority of any manifests in the product flavor groups follows the order in which the
-product flavor groups are listed in the build file. The manifest merge process creates a single
-merged manifest for the product flavor groups based on the configured build variant.
For example, if a build variant references the product flavors x86,
-mdpi, 21, and paid from the respective product flavor
-groups ABI, Density, API, and Prod, listed
-in this order in the build.gradle file, then the manifest merge process merges the
-manifests in this priority order, which follows how the product flavors are listed in the build
-file.
To illustrate this example, the following table shows how the product flavors are listed for -each product flavor group. This combination of product flavors and groups defines the -build variant.
-| Product Flavor Group | -Product Flavor | -
|---|---|
| ABI | -x86 | -
| density | -mdpi | -
| API | -22 | -
| prod | -paid | -
Manifest merge order:
- -Importing a library that targets an Android runtime with implicitly
-granted permissions may automatically add the permissions to the resulting merged manifest.
-For example, if an application with a targetSdkVersion of 16 imports a library with a
-targetSdkVersion of 2, Android Studio adds the WRITE_EXTERNAL_STORAGE
-permission to ensure permission compatibility across the SDK versions.
-
-
Note: More recent Android releases replace implicit -permissions with permission declarations.
- - -This table lists the importing library versions and the declared permissions. - - -| Importing this library version | -Declares this permission in the manifest | -
|---|---|
targetSdkVersion < 2 |
- WRITE_EXTERNAL_STORAGE |
-
targetSdkVersion < 4 |
- WRITE_EXTERNAL_STORAGE, READ_PHONE_STATE |
-
Declared WRITE_EXTERNAL_STORAGE |
- READ_EXTERNAL_STORAGE |
-
targetSdkVersion < 16 and using the READ_CONTACTS
- permission |
- READ_CALL_LOG |
-
targetSdkVersion < 16 and using the WRITE_CONTACTS
- permission |
- WRITE_CALL_LOG |
-
During the build process, the manifest merge process stores a record of each merge transaction
-in the manifest-merger-<productFlavor>-report.txt file in the module
-build/outputs/logs folder. A different log file is generated for each of the
-module's build variants.
When a manifest merge build error occurs, the merge process records the error message
-describing the merge conflict in the log file. For example, the
-android:screenOrientation merge conflict between the following manifests causes
-a build error.
Higher priority manifest declaration:
- --<activity - android:name="com.foo.bar.ActivityOne" - android:screenOrientation="portrait" - android:theme="@theme1"/> -- -
Lower priority manifest declaration:
- --<activity - android:name="com.foo.bar.ActivityOne" - android:screenOrientation="landscape"/> -- -
Error log:
- --/project/app/src/main/AndroidManifest.xml:3:9 Error: - Attribute activity@screenOrientation value=(portrait) from AndroidManifest.xml:3:9 - is also present at flavorlib:lib1:unspecified:3:18 value=(landscape) - Suggestion: add 'tools:replace="icon"' to- - diff --git a/docs/html/tools/building/multidex.jd b/docs/html/tools/building/multidex.jd deleted file mode 100644 index 7d05fb93de4a294478bb402fc6f5ae9b9ec88010..0000000000000000000000000000000000000000 --- a/docs/html/tools/building/multidex.jd +++ /dev/null @@ -1,488 +0,0 @@ -page.title=Building Apps with Over 64K Methods -page.tags="65536","references","max","65k","dex","64k","multidex","multi-dex","methods" - -@jd:body - -element at AndroidManifest.xml:1:5 to override -
- As the Android platform has continued to grow, so has the size of Android apps. When your - application and the libraries it references reach a certain size, you encounter build errors that - indicate your app has reached a limit of the Android app build architecture. Earlier versions of - the build system report this error as follows: -
- --Conversion to Dalvik format failed: -Unable to execute dex: method ID not in [0, 0xffff]: 65536 -- -
- More recent versions of the Android build system display a different error, which is an - indication of the same problem: -
- --trouble writing output: -Too many field references: 131000; max is 65536. -You may try using --multi-dex option. -- -
- Both these error conditions display a common number: 65,536. This number is significant in that - it represents the total number of references that can be invoked by the code within a single - Dalvik Executable (dex) bytecode file. If you have built an Android app and received this error, - then congratulations, you have a lot of code! This document explains how to move past this - limitation and continue building your app. -
- -- Note: The guidance provided in this document supersedes the guidance given in - the Android Developers blog post Custom Class - Loading in Dalvik. -
- - -- Android application (APK) files contain executable bytecode files in the form - of Dalvik - Executable (DEX) files, which contain the compiled code used to run your app. - The Dalvik Executable specification limits the total number of methods that - can be referenced within a single DEX file to 65,536—including Android - framework methods, library methods, and methods in your own code. In the - context of computer science, the term Kilo, K, denotes 1024 (or - 2^10). Because 65,536 is equal to 64 X 1024, this limit is referred to as the - '64K reference limit'. -
- -- Getting past this limit requires that you configure your app build process to - generate more than one DEX file, known as a multidex configuration. -
- -- Versions of the platform prior to Android 5.0 (API level 21) use the Dalvik - runtime for executing app code. By default, Dalvik limits apps to a single - classes.dex bytecode file per APK. In order to get around this limitation, - you can use the multidex support - library, which becomes part of the primary DEX file of your app and then - manages access to the additional DEX files and the code they contain. -
- -
- Note: If your project is configured for multidex with
- minSdkVersion 20 or lower, and you deploy to target devices
- running Android 4.4 (API level 20) or lower, Android Studio disables Instant Run.
-
- Android 5.0 (API level 21) and higher uses a runtime called ART which - natively supports loading multiple dex files from application APK files. ART - performs pre-compilation at application install time which scans for - classes(..N).dex files and compiles them into a single .oat file for - execution by the Android device. For more information on the Android 5.0 - runtime, see Introducing - ART. -
- -
- Note: While using Instant Run,
- Android Studio automatically configures your app for multidex when your app's
- minSdkVersion is set to 21 or higher. Because Instant Run only
- works with the debug version of your app, you still need to configure your
- release build for multidex to avoid the 64K limit.
-
- Before configuring your app to enable use of 64K or more method references, you should take steps - to reduce the total number of references called by your app code, including methods defined by - your app code or included libraries. The following strategies can help you avoid hitting the dex - reference limit: -
- -- Using these techniques can help you avoid the build configuration changes required to enable more - method references in your app. These steps can also decrease the size of your APKs, which is - particularly important for markets where bandwidth costs are high. -
- - -- The Android plugin for Gradle available in Android SDK Build Tools 21.1 and higher supports - multidex as part of your build configuration. Make sure you update the Android SDK Build Tools - tools and the Android Support Repository to the latest version using the SDK Manager before attempting to configure your app - for multidex. -
- -- Setting up your app development project to use a multidex configuration requires that you make a - few modifications to your app development project. In particular you need to perform the - following steps: -
- -
- Modify the module-level build.gradle file configuration to
- include the support library and enable multidex output, as shown in the
- following code snippet:
-
-android {
- compileSdkVersion 21
- buildToolsVersion "21.1.0"
-
- defaultConfig {
- ...
- minSdkVersion 14
- targetSdkVersion 21
- ...
-
- // Enabling multidex support.
- multiDexEnabled true
- }
- ...
-}
-
-dependencies {
- compile 'com.android.support:multidex:1.0.0'
-}
-
-
-- In your manifest add the {@link android.support.multidex.MultiDexApplication} class from the - multidex support library to the application element. -
- --<?xml version="1.0" encoding="utf-8"?> -<manifest xmlns:android="http://schemas.android.com/apk/res/android" - package="com.example.android.multidex.myapplication"> - <application - ... - android:name="android.support.multidex.MultiDexApplication"> - ... - </application> -</manifest> -- -
- When these configuration settings are added to an app, the Android build tools construct a - primary dex (classes.dex) and supporting (classes2.dex, classes3.dex) as needed. The build system - will then package them into an APK file for distribution. -
- -- Note: If your app uses extends the {@link android.app.Application} class, you - can override the attachBaseContext() method and call MultiDex.install(this) to enable multidex. - For more information, see the {@link android.support.multidex.MultiDexApplication} reference - documentation. -
- -- The multidex support library has some known limitations that you should be aware of and test for - when you incorporate it into your app build configuration: -
- -- A multidex configuration requires significantly increased build processing time because the build - system must make complex decisions about what classes must be included in the primary DEX file - and what classes can be included in secondary DEX files. This means that routine builds performed - as part of the development process with multidex typically take longer and can potentially slow - your development process. -
- -- In order to mitigate the typically longer build times for multidex output, you should create two - variations on your build output using the Android plugin for Gradle - - {@code productFlavors}: a development flavor and a production flavor. -
- -- For the development flavor, set a minimum SDK version of 21. This setting generates multidex - output much faster using the ART-supported format. For the release flavor, set a minimum SDK - version which matches your actual minimum support level. This setting generates a multidex APK - that is compatible with more devices, but takes longer to build. -
- -- The following build configuration sample demonstrates the how to set up these flavors in a Gradle - build file: -
- -
-android {
- productFlavors {
- // Define separate dev and prod product flavors.
- dev {
- // dev utilizes minSDKVersion = 21 to allow the Android gradle plugin
- // to pre-dex each module and produce an APK that can be tested on
- // Android Lollipop without time consuming dex merging processes.
- minSdkVersion 21
- }
- prod {
- // The actual minSdkVersion for the application.
- minSdkVersion 14
- }
- }
- ...
- buildTypes {
- release {
- runProguard true
- proguardFiles getDefaultProguardFile('proguard-android.txt'),
- 'proguard-rules.pro'
- }
- }
-}
-dependencies {
- compile 'com.android.support:multidex:1.0.0'
-}
-
-
-
- After you have completed this configuration change, you can use the devDebug variant
- of your app, which combines the attributes of the dev productFlavor and the
- debug buildType. Using this target creates a debug app with proguard disabled,
- multidex enabled, and minSdkVersion set to Android API level 21. These settings cause the Android
- gradle plugin to do the following:
-
- These settings result in fast, incremental builds, because only the dex files of modified modules - are recomputed and repackaged into the APK file. The APK that results from these builds can be - used to test on Android 5.0 devices only. However, by implementing the configuration as a flavor, - you preserve the ability to perform normal builds with the release-appropriate minimum SDK level - and proguard settings. -
- -
- You can also build the other variants, including a prodDebug variant
- build, which takes longer to build, but can be used for testing outside of development.
- Within the configuration shown, the prodRelease variant would be the final testing
- and release version. If you are executing gradle tasks from the command line, you can use
- standard commands with DevDebug appended to the end (such as ./gradlew
- installDevDebug). For more information about using flavors with Gradle tasks, see the
- Gradle Plugin User
- Guide.
-
- Tip: You can also provide a custom manifest, or a custom application class for each - flavor, allowing you to use the support library MultiDexApplication class, or calling - MultiDex.install() only for the variants that need it. -
- - -- Build variants can be very useful for managing the build process when using multidex. Android - Studio allows you to select these build variants in the user interface. -
- -- To have Android Studio build the "devDebug" variant of your app: -
- -
-- Figure 1. Screen shot of the Android Studio left panel showing a build variant. -
- -- Note: The option to open this window is only available after you have - successfully synchronized Android Studio with your Gradle build file using the Tools > - Android > Sync Project with Gradle Files command. -
- - -- When using instrumentation tests with multidex apps, additional configuration is required to - enable the test instrumentation. Because the location of code for classes in multidex apps is not - within a single DEX file, instrumentation tests do not run properly unless configured for - multidex. -
- -- To test a multidex app with instrumentation tests, configure the - - MultiDexTestRunner from the multidex testing support library. The following sample - {@code build.gradle} file demonstrates how to configure your build to use this test runner: -
- -
-android {
- defaultConfig {
- ...
- testInstrumentationRunner "com.android.test.runner.MultiDexTestRunner"
- }
-}
-
-
-
- Note: With Android Plugin for Gradle versions lower than 1.1, you need to add
- the following dependency for multidex-instrumentation:
-
-dependencies {
- androidTestCompile('com.android.support:multidex-instrumentation:1.0.1') {
- exclude group: 'com.android.support', module: 'multidex'
- }
-}
-
-
-
-
-- You may use the instrumentation test runner class directly or extend it to fit your testing - needs. Alternatively, you can override onCreate in existing instrumentations like this: -
- -
-public void onCreate(Bundle arguments) {
- MultiDex.install(getTargetContext());
- super.onCreate(arguments);
- ...
-}
-
-
-- Note: Use of multidex for creating a test APK is not currently supported. -
diff --git a/docs/html/tools/building/plugin-for-gradle.jd b/docs/html/tools/building/plugin-for-gradle.jd deleted file mode 100644 index aed1af2d61b8bdac610f1495171928217272395a..0000000000000000000000000000000000000000 --- a/docs/html/tools/building/plugin-for-gradle.jd +++ /dev/null @@ -1,450 +0,0 @@ -page.title=Android Plugin for Gradle - -@jd:body - -The Android build system consists of an Android plugin for Gradle. -Gradle is an advanced build toolkit that manages -dependencies and allows you to define custom build logic. Android Studio uses a Gradle wrapper -to fully integrate the Android plugin for Gradle. The Android plugin for Gradle also runs -independent of Android Studio. This means that you can build your Android apps from within Android -Studio and from the command line on your machine or on machines where Android Studio is not installed -(such as continuous integration servers).
- -The output of the build is the same whether you are building a project from the command line, -on a remote machine, or using Android Studio.
- -The build configuration for your project is defined inside build.gradle files,
-which are plain text files that use the syntax and options from Gradle and the Android plugin
-to configure the following aspects of your build:
apk files has a different
- application name, minimum SDK version, or target SDK version. When multiple manifests are
- present, manifest settings are merged in priority of buildType and productFlavor,
- /main manifest, and the library manifests.Gradle build files use Domain Specific Language (DSL) to describe and manipulate the build logic -through Groovy syntax. Groovy is a dynamic -language that you can use to define custom build logic and to interact with the Android-specific -elements provided by the Android plugin for Gradle.
- -The Android Studio build system assumes sensible defaults for the project structure -and other build options. If your project adheres to these conventions, your Gradle build files are -very simple. When some of these conventions do not apply to your project, the flexibility of the -build system allows you to configure almost every aspect of the build process. For example, if -you need to replace the default source folders in your module directories, you can configure a new -directory structure in the module's build file.
- -A project in Android Studio represents the top-level Android development structure. -Android Studio projects contain project files and one or more application modules. A -module is a component of your app that you can build, test, or debug independently. -Modules contain the source code and resources for your apps. Android Studio projects can contain -several kinds of modules:
- -Android Studio projects contain a top-level project Gradle build file that allows you to add the -configuration options common to all application modules in the project. Each application module -also has its own build.gradle file for build settings specific to that module.
- -By default, the project-level Gradle file uses buildscript to define the Gradle -repositories and dependencies. This allows different projects to use different -Gradle versions. Supported repositories include JCenter, Maven Central, or Ivy. This example -declares that the build script uses the JCenter repository and a classpath dependency artifact -that contains the Android plugin for Gradle version 1.0.1. -
--
-buildscript {
- repositories {
- jcenter()
- }
- dependencies {
- classpath 'com.android.tools.build:gradle:1.0.1'
-
- // NOTE: Do not place your application dependencies here: they belong
- // in the individual module build.gradle files
- }
-}
-
-allprojects {
- repositories {
- jcenter()
- }
-}
-
-
-Note: The SDK location for the Android Studio project is defined in
-the local.properties file in the sdk.dir setting or through an
-ANDROID_HOME environment variable.
The application module Gradle build file allows you to configure module build settings,
-including overriding the src/main manifest settings and setting custom packaging
-options.
This example applies the Android plugin, uses the default configuration to override several -manifest properties, creates two build types: release and debug, and declares several dependencies. -
- -
-apply plugin: 'com.android.application'
-
-android {
- compileSdkVersion 20
- buildToolsVersion "20.0.0"
-
- defaultConfig {
- applicationId "com.mycompany.myapplication"
- minSdkVersion 13
- targetSdkVersion 20
- versionCode 1
- versionName "1.0"
- }
-
- buildTypes {
- release {
- minifyEnabled false
- proguardFiles getDefaultProguardFile('proguard-android.txt'), 'proguard-rules.pro'
- }
- debug {
- debuggable true
- }
- }
-}
-
-dependencies {
- compile fileTree(dir: 'libs', include: ['*.jar'])
- compile 'com.android.support:appcompat-v7:20.0.0'
- compile project(path: ':app2, configuration: 'android-endpoints')
-}
-
-
-
-Note: You can inject custom build logic for property values defined -by a function that gets called by the property, for example: -
-def computeVersionName() {
- ...
-}
-
-android {
- defaultConfig {
- versionName computeVersionName()
- ...
- }
-}
-
-
-
-
-
-The Android Studio build system manages project dependencies and supports module dependencies, -local binary dependencies, and remote binary dependencies.
- -An application module can include in its build file a list of other modules it depends on. - When you build this module, the build system assembles and includes the required - modules.
If you have binary archives in your local filesystem that a module depends on, such as - JAR files, you can declare these dependencies in the build file for that module.
When some of your dependencies are available in a remote repository, you do not have - to download them and copy them into your project. The Android Studio build system supports - remote dependencies from repositories, such as Maven, - and dependency managers, such as Ivy.
-Many popular software libraries and tools are available in public Maven repositories.
- For these dependencies you only have to specify their Maven coordinates, which uniquely
- identify each element in a remote repository. The format for Maven coordinates used in the
- build system is group:name:version. For example, the Maven coordinates for
- version 16.0.1 of the Google Guava libraries are
- com.google.guava:guava:16.0.1.
The Maven Central Repository is widely used to - distribute many libraries and tools.
-The Android Studio build system defines a hierarchical set of build tasks: the top-level or -anchor tasks invoke dependent tasks to produce their collective build outcomes. The top-level build -tasks are:
- -Builds the project output.
Runs checks and tests.
Runs both assemble and check.
Performs the clean.
The Android plugin provides the connectedCheck and deviceCheck tasks -for checks run on connected, emulated, and remote devices. Gradle tasks can be viewed by clicking -the Gradle tab in the right margin.
- -You can view the list of available tasks and invoke any task from Android Studio and from -the command line, as described in -Building and Running from Android Studio -and Build the project from -the command line.
- -Android Studio projects contain the Gradle wrapper, which consists of:
- -Note: You should submit all of these files to your source -control system.
- -Using the Gradle wrapper (instead of the local Gradle installation) ensures that -you always run the version of Gradle defined in the local.properties file. To configure your -project to use a newer version of Gradle, edit the properties file and specify the new version there. -
- -Android Studio reads the properties file from the Gradle wrapper directory inside your project -and runs the wrapper from this directory, so you can seamlessly work with multiple projects -that require different versions of Gradle.
- -Note: Android Studio does not use the shell scripts, so any -changes you make to them won't work when building from the IDE. You should define your custom -logic inside Gradle build files instead.
- -You can run the shell scripts to build your project from the command line on your development -machine and on other machines where Android Studio is not installed.
- -Caution: When you create a project, only use the Gradle wrapper -scripts and JAR from a trusted source, such as those generated by Android Studio.
- - -Each version of your app is represented in the build system by a build variant. -Build variants are combinations of product flavors and build types. Product flavors represent -product build versions of an app, such as free and paid. Build types represent the build -packaging versions generated for each app package, such as debug and release. The build system -generates APKs for each combination of product flavor and build type.
- -By default, Android Studio defines default configuration settings, defaultConfig in
-the build.gradle file, and two build types (debug and release). This creates two
-build variants, debug and release, and the build system generates an
-APK for each variant.
Adding two product flavors, demo and full along -with the default build types debug and release generates four build variants, -each with its own customized configuration:
- -The priority of the merge order from lowest to highest is libraries/dependencies -> main src -> -productFlavor -> buildType.
- - -Some projects have complex combinations of features along more than one dimension, but they -still represent the same app. For example, in addition to having a demo and a full version of the -app, some games may contain binaries specific to a particular CPU/ABI. The flexibility of -the build system makes it possible to generate the following build variants for such a project:
- -This project would consist of two build types (debug and release) -and two dimensions of product flavors, one for app type (demo or full) and one for -CPU/ABI (x86, ARM, or MIPS).
- - -To build each version of your app, the build system combines source code and -resources from:
- -src/main/ - the main source directory (the default configuration common to all
- variants)src/<buildType>/ - the src/<productFlavor>/ - the Note: The build type and product flavor source directories are optional, -as Android Studio does not create these directories for you. You should create these directories -as you add build types and product flavors to the build configuration files. The build system does not -use these directories if they are not present.
- -For projects that do not define any flavors, the build system uses the defaultConfig -settings, the main app directory and the default build type directories. For example, to generate -the default debug and release build variants in projects with no product flavors, -the build system uses:
-src/main/ (default configuration)src/release/ (build type)src/debug/ (build type)For projects that define a set of product flavors, the build system merges the build type, product -flavor and main source directories. For example, to generate the full-debug build variant, -the build system merges the build type, product flavor and main directories:
-src/main/ (default configuration)src/debug/ (build type)src/full/ (flavor)For projects that use flavor dimensions, the build system merges one flavor source directory per -dimension. For example, to generate the arm-demo-release build variant, the build system -merges:
-src/main/ (default configuration)src/release/ (build type)src/demo/ (flavor - app type dimension)src/arm/ (flavor - ABI dimension)The source code from these directories is used together to generate the output for a build -variant. You can have classes with the same name in different directories as long as those -directories are not used together in the same variant.
- -The build system also merges all the manifests into a single manifest, so each build variant -can define different components or permissions in the final manifest. The manifest merge priority -from lowest to highest is libraries/dependencies -> main src -> productFlavor -> buildType.
- -The build system merges all the resources from the all the source directories. If different -folders contain resources with the same name for a build variant, the priority order is the -following: build type resources override those from the product flavor, which override the -resources in the main source directory, which override those in any libraries.
- -Note: Build variants enable you to reuse common activities, -application logic, and resources across different versions of your app.
- - diff --git a/docs/html/tools/debugging/annotations.jd b/docs/html/tools/debugging/annotations.jd deleted file mode 100644 index fbdb9e4bbfd52bc20ebf60ff557b037cdf3d110b..0000000000000000000000000000000000000000 --- a/docs/html/tools/debugging/annotations.jd +++ /dev/null @@ -1,377 +0,0 @@ -page.title=Improving Code Inspection with Annotations -@jd:body - -Using code inspections tools such as lint can help -you find problems and improve your code, but inspection tools can only infer so much. Android -resource ids, for example, use an {@code int} to identify strings, graphics, colors and other -resource types, so inspection tools cannot tell when you have specified a string resource where -you should have specified a color. This situation means that your app may render incorrectly or -fail to run at all, even if you use code inspection.
- -Annotations allow you to provide hints to code inspections tools like {@code lint}, to help -detect these, more subtle code problems. They are added as metadata tags that you attach to -variables, parameters, and return values to inspect method return values, passed parameters, and -local variables and fields. When used with code inspections tools, annotations can help you detect -problems, such as null pointer exceptions and resource type -conflicts.
- -For more information on enabling lint inspections -and running lint, -see Improving Your Code with lint.
- -Android supports a variety of annotations for insertion in the methods, parameters, and return -values in your code, for example:
- -R.string
- resource.Drawable
- resource. Color
- resource. Interpolator
- resource. R.
- resource. @UiThreadFor a complete list of the supported annotations, either examine the contents of the
-{@link android.support.annotation Support-Annotations} library or use the
-auto-complete feature to display the available options for the import
-android.support.annotation. statement. The
- SDK Manager packages the
-{@link android.support.annotation Support-Annotations} library in the Android Support Repository
-for use with Android Studio and in the Android
-Support Library for use with other Android
-development tools.
To add annotations to your code, first add a dependency to the
-{@link android.support.annotation Support-Annotations} library. In Android Studio,
-add the dependency using the File > Project Structure > Dependencies menu
-option or your build.gradle file. The following example shows how to add the
-{@link android.support.annotation Support-Annotations} library dependency in the
-build.gradle file:
-dependencies {
- compile 'com.android.support:support-annotations:22.2.0'
-}
-
-
-
-The {@link android.support.annotation Support-Annotations} library is decorated with the -supported annotations so using this library's methods and resources automatically checks the code -for potential problems.
- -If you include annotations in a library and use the
-Android Plugin for Gradle
-to build an Android ARchive (AAR) artifact of that library, the annotations are included as part
-of the artifact in XML format in the annotations.zip file.
To start a code inspection from Android Studio, which includes validating annotations and -automatic lint checking, select -Analyze > Inspect Code from the menu options. Android Studio displays conflict -messages throughout the code to indication annotation conflicts and suggest possible -resolutions.
- - -Add {@link android.support.annotation.Nullable @Nullable} and -{@link android.support.annotation.NonNull @NonNull} annotations to check -the nullness of a given variable, parameter, or return value. For example, if a local variable -that contains a null value is passed as a parameter to a method with the -{@link android.support.annotation.NonNull @NonNull} annotation -attached to that parameter, building the code generates a warning indicating a non-null conflict.
- -This example attaches the {@link android.support.annotation.NonNull @NonNull} annotation to
-the context and attrs parameters to check that the passed parameter
-values are not null.
-import android.support.annotation.NonNull;
-...
-
- /** Add support for inflating the <fragment> tag. */
- @NonNull
- @Override
- public View onCreateView(String name, @NonNull Context context,
- @NonNull AttributeSet attrs) {
- ...
- }
-...
-
-
-Note: Android Studio supports running a nullability analysis to -automatically infer and insert nullness annotations in your code. For more information about -inferring nullability in Android Studio, see -Annotations in Android Studio.
- - -Validating resource types can be useful as Android references to resources, such as
-Drawables and
-R.string resources, are
-passed as integers. Code that expects a parameter to reference a specific type of resource, for
-example Drawables,
-can be passed the expected reference type of int, but actually reference a different
-type of resource, such as a R.string resource.
For example, add {@link android.support.annotation.StringRes @StringRes} annotations to check
-that a resource parameter contains a
-R.string
-reference. During code inspection, the annotation generates a warning if a R.string
-reference is not passed in the parameter.
This example attaches the {@link android.support.annotation.StringRes @StringRes}
-annotation to the resId parameter to validate that it is really a string resource.
-import android.support.annotation.StringRes; -... - public abstract void setTitle(@StringRes int resId); - ... -- - -
Annotations for the other resource types, such as -{@link android.support.annotation.DrawableRes @DrawableRes}, -{@link android.support.annotation.DimenRes @DimenRes}, -{@link android.support.annotation.ColorRes @ColorRes}, and -{@link android.support.annotation.InterpolatorRes @InterpolatorRes} can be added using -the same annotation format and run during the code inspection.
- - - - -Thread annotations check if a method is called from a specific type of -thread. The following thread -annotations are supported:
-@UiThread @MainThread @WorkerThread @BinderThread
-Note: The @MainThread
-and the @UiThread annotations are interchangeable so
-methods calls from either thread type are allowed for these annotations.
If all methods in a class share the same threading requirement, you can add a single -thread -annotation to the class to verify that all methods in the class are called from the same type of -thread.
- -A common use of the thread -annotation is to validate method overrides in the -AsyncTask class as this class performs -background operations and publishes results only on the UI -thread.
- - - -Use the @IntRange,
-@FloatRange, and
-@Size annotations to validate the values of passed
-parameters.
The @IntRange annotation validates that the parameter
-value is within a specified range. The following example ensures that the alpha
-parameter contains an integer value from 0 to 255:
-public void setAlpha(@IntRange(from=0,to=255) int alpha) { … }
-
-
-The @FloatRange annotation checks that the parameter
-value is within a specified range of floating point values. The following example ensures that the
-alpha parameter contains a float value from 0.0 to 1.0:
-public void setAlpha(@FloatRange(from=0.0, to=1.0) float alpha) {...}
-
-
-The @Size annotation checks the size of a collection or
-array, as well as the length of a string. For example, use the @Size(min=1)
-annotation to check if a collection is not empty, and the @Size(2) annotation to
-validate that an array contains exactly two values. The following example ensures that the
-location array contains at least one element:
-int[] location = new int[3]; -button.getLocationOnScreen(@Size(min=1) location); -- - -
Use the @RequiresPermission annotation to
-validate the permissions of the caller of a method. To check for a single permission from a
-list the valid permissions, use the anyOf attribute. To check for a set of
-permissions, use the allOf attribute. The following example annotates the
-setWallpaper method to ensure that the caller of the method has the
-permission.SET_WALLPAPERS permission.
-@RequiresPermission(Manifest.permission.SET_WALLPAPER) -public abstract void setWallpaper(Bitmap bitmap) throws IOException; -- -
This example requires the caller of the {@code copyFile()} method to have both read and write -permissions to external storage:
-
-@RequiresPermission(allOf = {
- Manifest.permission.READ_EXTERNAL_STORAGE,
- Manifest.permission.WRITE_EXTERNAL_STORAGE})
-public static final void copyFile(String dest, String source) {
- ...
-}
-
-
-Use the @CheckResults annotation to
-validate that a method's result or return value is actually used. The following example annotates
-the checkPermissions method to ensure the return value of the method is actually
-referenced. It also names the
-enforcePermission
-method as a method to be suggested to the developer as a replacement.
-@CheckResult(suggest="#enforcePermission(String,int,int,String)") -public abstract int checkPermission(@NonNull String permission, int pid, int uid); -- -{@link android.support.annotation.StringDef @StringDef} - - -
Use the @CallSuper annotation to validate that an
-overriding method calls the super implementation of the method. The following example annotates
-the onCreate method to ensure that any overriding method implementations call
-super.onCreate().
-@CallSuper
-protected void onCreate(Bundle savedInstanceState) {
-}
-
-
-
-
-Use the {@link android.support.annotation.IntDef @IntDef} and -{@link android.support.annotation.StringDef @StringDef} annotations -so you can create enumerated annotations of integer and string sets to validate other types of code -references, such as passing references to a set of constants.
- -The following example illustrates the steps to create an enumerated annotation that ensures -a value passed as a method parameter references one of the defined constants.
- -
-import android.support.annotation.IntDef;
-...
-public abstract class ActionBar {
- ...
- //Define the list of accepted constants
- @IntDef({NAVIGATION_MODE_STANDARD, NAVIGATION_MODE_LIST, NAVIGATION_MODE_TABS})
-
- //Tell the compiler not to store annotation data in the .class file
- @Retention(RetentionPolicy.SOURCE)
-
- //Declare the NavigationMode annotation
- public @interface NavigationMode {}
-
- //Declare the constants
- public static final int NAVIGATION_MODE_STANDARD = 0;
- public static final int NAVIGATION_MODE_LIST = 1;
- public static final int NAVIGATION_MODE_TABS = 2;
-
- //Decorate the target methods with the annotation
- @NavigationMode
- public abstract int getNavigationMode();
-
- //Attach the annotation
- public abstract void setNavigationMode(@NavigationMode int mode);
-
-
-
-When you build this code, a warning is generated if the mode parameter does
-not reference one of the defined constants (NAVIGATION_MODE_STANDARD,
-NAVIGATION_MODE_LIST, or NAVIGATION_MODE_TABS).
You can also define an annotation with a flag to check if a parameter
-or return value references a valid pattern. This example creates the
-DisplayOptions annotation with a list of valid DISPLAY_ constants.
-import android.support.annotation.IntDef;
-...
-
-@IntDef(flag=true, value={
- DISPLAY_USE_LOGO,
- DISPLAY_SHOW_HOME,
- DISPLAY_HOME_AS_UP,
- DISPLAY_SHOW_TITLE,
- DISPLAY_SHOW_CUSTOM
-})
-@Retention(RetentionPolicy.SOURCE)
-public @interface DisplayOptions {}
-
-...
-
-
-When you build code with an annotation flag, a warning is generated if the decorated parameter -or return value does not reference a valid pattern.
- - diff --git a/docs/html/tools/debugging/ddms.jd b/docs/html/tools/debugging/ddms.jd deleted file mode 100644 index 9ff71222c8200fc6c2abf2d902ba52e124850eff..0000000000000000000000000000000000000000 --- a/docs/html/tools/debugging/ddms.jd +++ /dev/null @@ -1,312 +0,0 @@ -page.title=Using DDMS -parent.title=Debugging -parent.link=index.html -@jd:body - -Android Studio includes a debugging tool called the Dalvik Debug Monitor Server (DDMS), which - provides port-forwarding services, screen capture on the device, thread and heap information on - the device, logcat, process, and radio state information, incoming call and SMS spoofing, - location data spoofing, and more. This page provides a modest discussion of DDMS features; it is - not an exhaustive exploration of all the features and capabilities.
- -DDMS is integrated into Android Studio. To use it, launch the - Android Device Monitor, and click the - DDMS menu button. DDMS works with both the emulator and a - connected device. If both are connected and running simultaneously, DDMS defaults to the emulator.
- - -On Android, every application runs in its own process, each of which runs in its own virtual machine - (VM). Each VM exposes a unique port that a debugger can attach to.
- -When DDMS starts, it connects to adb.
- When a device is connected, a VM monitoring service is created between
- adb and DDMS, which notifies DDMS when a VM on the device is started or terminated. Once a VM
- is running, DDMS retrieves the VM's process ID (pid), via adb, and opens a connection to the
- VM's debugger, through the adb daemon (adbd) on the device. DDMS can now talk to the VM using a
- custom wire protocol.
DDMS assigns a debugging port to each VM on the device. Typically, - DDMS assigns port 8600 for the first debuggable VM, the next on 8601, and so on. When a debugger - connects to one of these ports, all traffic is forwarded to the debugger from the associated - VM. You can only attach a single debugger to a single port, but DDMS can handle multiple, attached - debuggers.
- -By default, DDMS also listens on another debugging port, the DDMS "base port" (8700, by default). - The base port is a port forwarder, which can accept VM traffic from any debugging port and forward - it to the debugger on port 8700. This allows you to attach one debugger to port 8700, and debug - all the VMs on a device. The traffic that is forwarded is determined by the currently selected process - in the DDMS Devices view.
- -The following screenshot shows a typical DDMS screen. If you are starting DDMS from
- the command line, the screen is slightly different, but much of the functionality is identical.
- Notice that the highlighted process, com.android.email, that is running in the emulator
- has the debugging port 8700 assigned to it as well as 8606. This signifies that DDMS is currently
- forwarding port 8606 to the static debugging port of 8700.
- Figure 1. - Screenshot of DDMS
- -If you are using the command line, read Configuring - your IDE to attach to the debugging port, for more information on attaching your - debugger.
- -Tip: You can set a number of DDMS preferences in
- File > Preferences. Preferences are saved to
- $HOME/.android/ddms.cfg.
Known debugging issues with Dalvik
- Debugging an application in the Dalvik VM should work the same as it does in other VMs. However,
- when single-stepping out of synchronized code, the "current line" cursor may jump to the last
- line in the method for one step.
DDMS allows you to view how much heap memory a process is using. This information is useful in - tracking heap usage at a certain point of time during the execution of your application.
-To view heap usage for a process:
-DDMS provides a feature to track objects that are being allocated to memory and to see which - classes and threads are allocating the objects. This allows you to track, in real time, where - objects are being allocated when you perform certain actions in your application. This - information is valuable for assessing memory usage that can affect application performance. -
- -To track memory allocation of objects:
-DDMS provides a File Explorer tab that allows you to view, copy, and delete files on the - device. This feature is useful in examining files that are created by your application or if you - want to transfer files to and from the device.
- -To work with an emulator or device's file system:
-The Threads tab in DDMS shows you the currently running threads for a selected process.
- -Method profiling is a means to track certain metrics about a method, such as number of calls, - execution time, and time spent executing the method. If you want more granular control over - where profiling data is collected, use the {@link android.os.Debug#startMethodTracing()} and - {@link android.os.Debug#stopMethodTracing()} methods. For more information about generating trace logs, see - Profiling and Debugging UIs.
- -Before you start method profiling in DDMS, be aware of the following restrictions:
-To start method profiling:
-In Android 4.0, the DDMS (Dalvik Debug Monitor Server) includes a Detailed -Network Usage tab that makes it possible to track when your application is -making network requests. Using this tool, you can monitor how and when your app -transfers data and optimize the underlying code appropriately. You can also -distinguish between different traffic types by applying a “tag” to network -sockets before use.
- -These tags are shown in a stack area chart in DDMS, as shown in figure 2:
- -
-Figure 2. Network Usage tab.
- -By monitoring the frequency of your data transfers, and the amount of data -transferred during each connection, you can identify areas of your application -that can be made more battery-efficient. Generally, you should look for -short spikes that can be delayed, or that should cause a later transfer to be -pre-empted.
- -To better identify the cause of transfer spikes, the -{@link android.net.TrafficStats} API allows you -to tag the data transfers occurring within a thread using {@link -android.net.TrafficStats#setThreadStatsTag setThreadStatsTag()}, followed -by manually tagging (and untagging) individual sockets using {@link -android.net.TrafficStats#tagSocket tagSocket()} and {@link -android.net.TrafficStats#untagSocket untagSocket()}. For example:
- -TrafficStats.setThreadStatsTag(0xF00D); -TrafficStats.tagSocket(outputSocket); -// Transfer data using socket -TrafficStats.untagSocket(outputSocket);- -
Alternatively, the {@link java.net.URLConnection} APIs included in the platform -automatically tag sockets internally based on the active tag (as identified by -{@link android.net.TrafficStats#getThreadStatsTag getThreadStatsTag()}). -These APIs correctly tag/untag sockets when recycled through -keep-alive pools. In the following example, -{@link android.net.TrafficStats#setThreadStatsTag setThreadStatsTag()} -sets the active tag to be {@code 0xF00D}. -There can only be one active tag per thread. -That is the value that will -be returned by {@link android.net.TrafficStats#getThreadStatsTag getThreadStatsTag()} -and thus used by the HTTP client to tag sockets. The {@code finally} statement -invokes -{@link android.net.TrafficStats#clearThreadStatsTag clearThreadStatsTag()} -to clear the tag.
- -TrafficStats.setThreadStatsTag(0xF00D);
- try {
- // Make network request using your http client.
- } finally {
- TrafficStats.clearThreadStatsTag();
-}
-
-Socket tagging is supported in Android 4.0, but real-time stats will only be -displayed on devices running Android 4.0.3 or higher.
- -LogCat is integrated into DDMS, and outputs the messages that you print out using the {@link android.util.Log} - class along with other system messages such as stack traces when exceptions are thrown. View the - Reading and - Writing Log Messages. topic for more information on how to log messages to the LogCat.
- -When you have set up your logging, you can use the LogCat feature of DDMS to filter certain - messages with the following buttons:
- -You can also setup your own custom filter to specify more details such as filtering messages - with the log tags or with the process id that generated the log message. The add filter, - edit filter, and delete filter buttons let you manage your custom filters.
- -The Emulator Control tab, shown in Figure 1, is no longer - supported. Use the - Android Emulator - for these features.
- - diff --git a/docs/html/tools/debugging/debugging-log.jd b/docs/html/tools/debugging/debugging-log.jd deleted file mode 100644 index a49e8c54422c860422b1150632fed60b9ebddd66..0000000000000000000000000000000000000000 --- a/docs/html/tools/debugging/debugging-log.jd +++ /dev/null @@ -1,307 +0,0 @@ -page.title=Reading and Writing Logs - -@jd:body - -The Android logging system provides a mechanism for collecting and viewing system debug - output. Logcat dumps a log of system messages, which include things such as stack traces when the - emulator throws an error and messages that you have written from your application by using the - {@link android.util.Log} class. You can run LogCat through ADB or from DDMS, which allows you to - read the messages in real time.
- -You can use LogCat from within DDMS or call it on an ADB shell. For more information on how to - use LogCat within DDMS, see Using - DDMS. To run LogCat, through the ADB shell, the general usage is:
--[adb] logcat [<option>] ... [<filter-spec>] ... -- -
You can use the logcat command from your development computer or from a remote
- adb shell in an emulator/device instance. To view log output in your development computer, you
- use
-$ adb logcat -- -
and from a remote adb shell you use
--# logcat -- -
The following table describes the logcat command line options:
-c |
-
- Clears (flushes) the entire log and exits. | -
-d |
-
- Dumps the log to the screen and exits. | -
-f <filename> |
-
- Writes log message output to <filename>. The default is
- stdout. |
-
-g |
- Prints the size of the specified log buffer and exits. | -
-n <count> |
-
- Sets the maximum number of rotated logs to <count>. The default value
- is 4. Requires the -r option. |
-
-r <kbytes> |
-
- Rotates the log file every <kbytes> of output. The default value is
- 16. Requires the -f option. |
-
-s |
-
- Sets the default filter spec to silent. | -
-v <format> |
-
- Sets the output format for log messages. The default is brief format. For a
- list of supported formats, see Controlling Log Output
- Format. |
-
Every Android log message has a tag and a priority associated with it.
- -V — Verbose (lowest priority)D — DebugI — InfoW — WarningE — ErrorF — FatalS — Silent (highest priority, on which nothing is ever printed)You can obtain a list of tags used in the system, together with priorities, by running
- LogCat and observing the first two columns of each message, given as
- <priority>/<tag>.
Here's an example of logcat output that shows that the message relates to priority level "I" - and tag "ActivityManager":
-
-I/ActivityManager( 585): Starting activity: Intent { action=android.intent.action...}
-
-
- To reduce the log output to a manageable level, you can restrict log output using filter - expressions. Filter expressions let you indicate to the system the tags-priority - combinations that you are interested in — the system suppresses other messages for the - specified tags.
- -A filter expression follows this format tag:priority ..., where tag
- indicates the tag of interest and priority indicates the minimum level of
- priority to report for that tag. Messages for that tag at or above the specified priority are
- written to the log. You can supply any number of tag:priority specifications in a
- single filter expression. The series of specifications is whitespace-delimited.
Here's an example of a filter expression that suppresses all log messages except those with - the tag "ActivityManager", at priority "Info" or above, and all log messages with tag "MyApp", - with priority "Debug" or above:
--adb logcat ActivityManager:I MyApp:D *:S -- -
The final element in the above expression, *:S, sets the priority level for all
- tags to "silent", thus ensuring only log messages with "ActivityManager" and "MyApp" are displayed. Using
- *:S is an excellent way to ensure that log output is restricted to the filters that
- you have explicitly specified — it lets your filters serve as a "whitelist" for log
- output.
The following filter expression displays all log messages with priority level "warning" and higher, on all tags:
--adb logcat *:W -- -
If you're running LogCat from your development computer (versus running it on a
- remote adb shell), you can also set a default filter expression by exporting a value for the
- environment variable ANDROID_LOG_TAGS:
-export ANDROID_LOG_TAGS="ActivityManager:I MyApp:D *:S" -- -
Note that ANDROID_LOG_TAGS filter is not exported to the emulator/device
- instance, if you are running LogCat from a remote shell or using adb shell
- logcat.
Log messages contain a number of metadata fields, in addition to the tag and priority. You can
- modify the output format for messages so that they display a specific metadata field. To do so,
- you use the -v option and specify one of the supported output formats listed
- below.
brief — Display priority/tag and PID of the process issuing the
- message (the default format).process — Display PID only.tag — Display the priority/tag only.raw — Display the raw log message, with no other metadata fields.time — Display the date, invocation time, priority/tag, and PID of the
- process issuing the message.threadtime — Display the date, invocation time, priority, tag, and
- the PID and TID of the thread issuing the message.long — Display all metadata fields and separate messages with blank
- lines.When starting LogCat, you can specify the output format you want by using the
- -v option:
-[adb] logcat [-v <format>] -- -
Here's an example that shows how to generate messages in thread output
- format:
-adb logcat -v thread -- -
Note that you can only specify one output format with the -v option.
The Android logging system keeps multiple circular buffers for log messages, and not all of
- the log messages are sent to the default circular buffer. To see additional log messages, you can
- run the logcat command with the -b option, to request viewing of an alternate
- circular buffer. You can view any of these alternate buffers:
radio — View the buffer that contains radio/telephony related
- messages.events — View the buffer containing events-related messages.main — View the main log buffer (default)The usage of the -b option is:
-[adb] logcat [-b <buffer>] -- -
Here's an example of how to view a log buffer containing radio and telephony messages:
--adb logcat -b radio -- -
By default, the Android system sends stdout and stderr
- (System.out and System.err) output to /dev/null. In
- processes that run the Dalvik VM, you can have the system write a copy of the output to the log
- file. In this case, the system writes the messages to the log using the log tags
- stdout and stderr, both with priority I.
To route the output in this way, you stop a running emulator/device instance and then use the
- shell command setprop to enable the redirection of output. Here's how you do it:
-$ adb shell stop -$ adb shell setprop log.redirect-stdio true -$ adb shell start -- -
The system retains this setting until you terminate the emulator/device instance. To use the
- setting as a default on the emulator/device instance, you can add an entry to
- /data/local.prop on the device.
The {@link android.util.Log} class allows you to create log entries in your code that display - in the LogCat tool. Common logging methods include:
- -For example, using the following call:
- -
-Log.i("MyActivity", "MyClass.getView() — get item number " + position);
-
-
- The LogCat outputs something like:
--I/MyActivity( 1557): MyClass.getView() — get item number 1 -diff --git a/docs/html/tools/debugging/debugging-memory.jd b/docs/html/tools/debugging/debugging-memory.jd deleted file mode 100755 index 4e2e5193c9ba6783b42dd6ac9dedde1252fdb851..0000000000000000000000000000000000000000 --- a/docs/html/tools/debugging/debugging-memory.jd +++ /dev/null @@ -1,708 +0,0 @@ -page.title=Investigating Your RAM Usage -page.tags=memory,OutOfMemoryError -@jd:body - -
Because Android is designed for mobile devices, you should always be careful about how much -random-access memory (RAM) your app uses. Although Dalvik and ART perform -routine garbage collection (GC), this doesn’t mean you can ignore when and where your app allocates and -releases memory. In order to provide a stable user experience that allows the system to quickly -switch between apps, it is important that your app does not needlessly consume memory when the user -is not interacting with it.
- -Even if you follow all the best practices for Managing Your App Memory during -development (which you should), you still might leak objects or introduce other memory bugs. The -only way to be certain your app is using as little memory as possible is to analyze your app’s -memory usage with tools. This guide shows you how to do that.
- - -The simplest place to begin investigating your app’s memory usage is the runtime log messages. -Sometimes when a GC occurs, a message is printed to -logcat. The logcat output is also available in the -Device Monitor or directly in an IDE such as Android Studio.
- -In Dalvik (but not ART), every GC prints the following information to logcat:
- --D/dalvikvm: <GC_Reason> <Amount_freed>, <Heap_stats>, <External_memory_stats>, <Pause_time> -- -
Example:
- --D/dalvikvm( 9050): GC_CONCURRENT freed 2049K, 65% free 3571K/9991K, external 4703K/5261K, paused 2ms+2ms -- -
GC_CONCURRENTGC_FOR_MALLOCGC_HPROF_DUMP_HEAPGC_EXPLICIT
-GC_EXTERNAL_ALLOCAs these log messages accumulate, look out for increases in the heap stats (the -{@code 3571K/9991K} value in the above example). If this value continues to increase, you may have -a memory leak.
- - -Unlike Dalvik, ART doesn't log messages for GCs that were not explicitly requested. GCs are only -printed when they are they are deemed slow. More precisely, if the GC pause exceeds than 5ms or -the GC duration exceeds 100ms. If the app is not in a pause perceptible process state, -then none of its GCs are deemed slow. Explicit GCs are always logged.
- -ART includes the following information in its garbage collection log messages:
- --I/art: <GC_Reason> <GC_Name> <Objects_freed>(<Size_freed>) AllocSpace Objects, <Large_objects_freed>(<Large_object_size_freed>) <Heap_stats> LOS objects, <Pause_time(s)> -- -
Example:
- --I/art : Explicit concurrent mark sweep GC freed 104710(7MB) AllocSpace objects, 21(416KB) LOS objects, 33% free, 25MB/38MB, paused 1.230ms total 67.216ms -- -
ConcurrentAllocExplicit
-NativeAllocCollectorTransitionHomogeneousSpaceCompactDisableMovingGcHeapTrimConcurrent mark sweep (CMS)Concurrent partial mark sweepConcurrent sticky mark sweepMarksweep + semispaceIf you are seeing a large amount of GCs in logcat, look for increases in the heap stats (the -{@code 25MB/38MB} value in the above example). If this value continues to increase and doesn't -ever seem to get smaller, you could have a memory leak. Alternatively, if you are seeing GC which -are for the reason "Alloc", then you are already operating near your heap capacity and can expect -OOM exceptions in the near future.
- -To get a little information about what kind of memory your app is using and when, you -can view real-time updates to your app's heap in Android Studio's -HPROF viewer or in the Device Monitor:
- -Use Android Studio to view your app's memory use:
-
)
- in the Memory Monitor toolbar.
- Android Studio creates the heap snapshot file with the filename
- Snapshot-yyyy.mm.dd-hh.mm.ss.hprof in the Captures tab.
Note: To convert a heap dump to standard HPROF format in - Android Studio, right-click a heap snapshot in the Captures view and select - Export to standard .hprof.
)
- icon to cause heap allocation.
- From your <sdk>/tools/ directory, launch the monitor tool.
The Heap view shows some basic stats about your heap memory usage, updated after every -GC. To see the first update, click the Cause GC button.
- -
-Figure 1. The Device Monitor tool, -showing the [1] Update Heap and [2] Cause GC buttons. -The Heap tab on the right shows the heap results.
- - -Continue interacting with your app to watch your heap allocation update with each garbage -collection. This can help you identify which actions in your app are likely causing too much -allocation and where you should try to reduce allocations and release -resources.
- - - -As you start narrowing down memory issues, you should also use the Allocation Tracker to -get a better understanding of where your memory-hogging objects are allocated. The Allocation -Tracker can be useful not only for looking at specific uses of memory, but also to analyze critical -code paths in an app such as scrolling.
- -For example, tracking allocations when flinging a list in your app allows you to see all the -allocations that need to be done for that behavior, what thread they are on, and where they came -from. This is extremely valuable for tightening up these paths to reduce the work they need and -improve the overall smoothness of the UI.
- -To use the Allocation Tracker, open the Memory Monitor in Android Studio and click the - -Allocation Tracker icon. You can also track allocations in the Android Device Monitor:
- - -To use the Allocation Tracker in -Android Studio:
- -
) in the Memory Monitor tool bar to start and stop memory
- allocations.
- Android Studio creates the allocation file with the filename
- Allocations-yyyy.mm.dd-hh.mm.ss.alloc in the Captures tab.
From your <sdk>/tools/ directory, launch the monitor tool.
The list shows all recent allocations, -currently limited by a 512-entry ring buffer. Click on a line to see the stack trace that led to -the allocation. The trace shows you not only what type of object was allocated, but also in which -thread, in which class, in which file and at which line.
- -
-Figure 2. The Device Monitor tool, -showing recent app allocations and stack traces in the Allocation Tracker.
- - -Note: You will always see some allocations from {@code -DdmVmInternal} and elsewhere that come from the allocation tracker itself.
- -Although it's not necessary (nor possible) to remove all allocations from your performance -critical code paths, the allocation tracker can help you identify important issues in your code. -For instance, some apps might create a new {@link android.graphics.Paint} object on every draw. -Moving that object into a global member is a simple fix that helps improve performance.
- - - - - - -For further analysis, you may want to observe how your app's memory is -divided between different types of RAM allocation with the -following adb command:
- --adb shell dumpsys meminfo <package_name|pid> [-d] -- -
The -d flag prints more info related to Dalvik and ART memory usage.
- -The output lists all of your app's current allocations, measured in kilobytes.
- -When inspecting this information, you should be familiar with the -following types of allocation:
- -A nice characteristic of the PSS measurement is that you can add up the PSS across all processes to -determine the actual memory being used by all processes. This means PSS is a good measure for the -actual RAM weight of a process and for comparison against the RAM use of other processes and the -total available RAM.
- - -For example, below is the the output for Map’s process on a Nexus 5 device. There is a lot of -information here, but key points for discussion are listed below.
-adb shell dumpsys meminfo com.google.android.apps.maps -d
-
-Note: The information you see may vary slightly from what is shown -here, as some details of the output differ across platform versions.
- --** MEMINFO in pid 18227 [com.google.android.apps.maps] ** - Pss Private Private Swapped Heap Heap Heap - Total Dirty Clean Dirty Size Alloc Free - ------ ------ ------ ------ ------ ------ ------ - Native Heap 10468 10408 0 0 20480 14462 6017 - Dalvik Heap 34340 33816 0 0 62436 53883 8553 - Dalvik Other 972 972 0 0 - Stack 1144 1144 0 0 - Gfx dev 35300 35300 0 0 - Other dev 5 0 4 0 - .so mmap 1943 504 188 0 - .apk mmap 598 0 136 0 - .ttf mmap 134 0 68 0 - .dex mmap 3908 0 3904 0 - .oat mmap 1344 0 56 0 - .art mmap 2037 1784 28 0 - Other mmap 30 4 0 0 - EGL mtrack 73072 73072 0 0 - GL mtrack 51044 51044 0 0 - Unknown 185 184 0 0 - TOTAL 216524 208232 4384 0 82916 68345 14570 - - Dalvik Details - .Heap 6568 6568 0 0 - .LOS 24771 24404 0 0 - .GC 500 500 0 0 - .JITCache 428 428 0 0 - .Zygote 1093 936 0 0 - .NonMoving 1908 1908 0 0 - .IndirectRef 44 44 0 0 - - Objects - Views: 90 ViewRootImpl: 1 - AppContexts: 4 Activities: 1 - Assets: 2 AssetManagers: 2 - Local Binders: 21 Proxy Binders: 28 - Parcel memory: 18 Parcel count: 74 - Death Recipients: 2 OpenSSL Sockets: 2 -- -
Here is an older dumpsys on Dalvik of the gmail app:
- --** MEMINFO in pid 9953 [com.google.android.gm] ** - Pss Pss Shared Private Shared Private Heap Heap Heap - Total Clean Dirty Dirty Clean Clean Size Alloc Free - ------ ------ ------ ------ ------ ------ ------ ------ ------ - Native Heap 0 0 0 0 0 0 7800 7637(6) 126 - Dalvik Heap 5110(3) 0 4136 4988(3) 0 0 9168 8958(6) 210 - Dalvik Other 2850 0 2684 2772 0 0 - Stack 36 0 8 36 0 0 - Cursor 136 0 0 136 0 0 - Ashmem 12 0 28 0 0 0 - Other dev 380 0 24 376 0 4 - .so mmap 5443(5) 1996 2584 2664(5) 5788 1996(5) - .apk mmap 235 32 0 0 1252 32 - .ttf mmap 36 12 0 0 88 12 - .dex mmap 3019(5) 2148 0 0 8936 2148(5) - Other mmap 107 0 8 8 324 68 - Unknown 6994(4) 0 252 6992(4) 0 0 - TOTAL 24358(1) 4188 9724 17972(2)16388 4260(2)16968 16595 336 - - Objects - Views: 426 ViewRootImpl: 3(8) - AppContexts: 6(7) Activities: 2(7) - Assets: 2 AssetManagers: 2 - Local Binders: 64 Proxy Binders: 34 - Death Recipients: 0 - OpenSSL Sockets: 1 - - SQL - MEMORY_USED: 1739 - PAGECACHE_OVERFLOW: 1164 MALLOC_SIZE: 62 -- -
Generally, you should be concerned with only the Pss Total and Private Dirty
-columns. In some cases, the Private Clean and Heap Alloc columns also offer
-interesting data. Here is some more information about the different memory allocations (the rows)
-you should observe:
-
-
Dalvik HeapPss Total includes all Zygote
-allocations (weighted by their sharing across processes, as described in the PSS definition above).
-The Private Dirty number is the actual RAM committed to only your app’s heap, composed of
-your own allocations and any Zygote allocation pages that have been modified since forking your
-app’s process from Zygote.
-
-Note: On newer platform versions that have the Dalvik
-Other section, the Pss Total and Private Dirty numbers for Dalvik Heap do
-not include Dalvik overhead such as the just-in-time compilation (JIT) and GC
-bookkeeping, whereas older versions list it all combined under Dalvik.
The Heap Alloc is the amount of memory that the Dalvik and native heap allocators keep
-track of for your app. This value is larger than Pss Total and Private Dirty
-because your process was forked from Zygote and it includes allocations that your process shares
-with all the others.
.so mmap and .dex mmap.so (native) and .dex (Dalvik or ART)
-code. The Pss Total number includes platform code shared across apps; the
-Private Clean is your app’s own code. Generally, the actual mapped size will be much
-larger—the RAM here is only what currently needs to be in RAM for code that has been executed by
-the app. However, the .so mmap has a large private dirty, which is due to fix-ups to the native
-code when it was loaded into its final address.
-.oat mmap.art mmap.Heap (only with -d flag).LOS (only with -d flag).GC (only with -d flag).JITCache (only with -d flag).Zygote (only with -d flag).NonMoving (only with -d flag).IndirectRef (only with -d flag)UnknownPss Total for Unknown takes into account sharing with Zygote, and Private Dirty
-is unknown RAM dedicated to only your app.
-TOTALThe Private Dirty and Private Clean are the total allocations within your
-process, which are not shared with other processes. Together (especially Private Dirty),
-this is the amount of RAM that will be released back to the system when your process is destroyed.
-Dirty RAM is pages that have been modified and so must stay committed to RAM (because there is no
-swap); clean RAM is pages that have been mapped from a persistent file (such as code being
-executed) and so can be paged out if not used for a while.
ViewRootImplAppContexts and ActivitiesNote: A {@link android.view.View} or {@link -android.graphics.drawable.Drawable} object also holds a reference to the {@link -android.app.Activity} that it's from, so holding a {@link android.view.View} or {@link -android.graphics.drawable.Drawable} object can also lead to your app leaking an {@link -android.app.Activity}.
- - -A heap dump is a snapshot of all the objects in your app's heap, stored in a binary format called -HPROF. Your app's heap dump provides information about the overall state of your app's heap so you -can track down problems you might have identified while viewing heap updates.
- - -To retrieve your heap dump from within Android Studio, use the -Memory Monitor and -HPROF viewer. - -
You can also still perform these procedures in the Android monitor:
-From your <sdk>/tools/ directory, launch the monitor tool.
-Figure 3. The Device Monitor tool, -showing the [1] Dump HPROF file button.
- -If you need to be more precise about when the dump is created, you can also create a heap dump -at the critical point in your app code by calling {@link android.os.Debug#dumpHprofData -dumpHprofData()}.
- -The heap dump is provided in a format that's similar to, but not identical to one from the Java -HPROF tool. The major difference in an Android heap dump is due to the fact that there are a large -number of allocations in the Zygote process. But because the Zygote allocations are shared across -all app processes, they don’t matter very much to your own heap analysis.
- -To analyze your heap dump, you can use Memory Monitor in Android Studio.
-You can also use a standard tool like jhat. However, first
-you'll need to convert the HPROF file from Android's format to the J2SE HPROF format. You can do
-this using the hprof-conv tool provided in the
-<sdk>/platform-tools/
-directory. Simply run the hprof-conv command with two arguments: the original HPROF
-file and the location to write the converted HPROF file. For example:
-hprof-conv heap-original.hprof heap-converted.hprof -- - - -
You can now load the converted file into a heap analysis tool that understands -the J2SE HPROF format.
- -When analyzing your heap, you should look for memory leaks caused by:
-While using the tools described above, you should aggressively stress your app code and try -forcing memory leaks. One way to provoke memory leaks in your app is to let it -run for a while before inspecting the heap. Leaks will trickle up to the top of the allocations in -the heap. However, the smaller the leak, the longer you need to run the app in order to see it.
- -You can also trigger a memory leak in one of the following ways:
-Tip: You can also perform the above steps by using the "monkey" -test framework. For more information on running the monkey test framework, read the monkeyrunner -documentation.
diff --git a/docs/html/tools/debugging/debugging-studio.jd b/docs/html/tools/debugging/debugging-studio.jd deleted file mode 100644 index 7e54634278fb2d1a89f7f50151c756dbc0c9b029..0000000000000000000000000000000000000000 --- a/docs/html/tools/debugging/debugging-studio.jd +++ /dev/null @@ -1,421 +0,0 @@ -page.title=Debugging with Android Studio - -@jd:body - -Android Studio enables you to debug apps running on the emulator or on an Android device. -With Android Studio, you can:
- -To debug your app, Android Studio builds a debuggable version of your app, connects -to a device or to the emulator, installs the app and runs it. The IDE shows the system log -while your app is running and provides debugging tools to filter log messages, work with -breakpoints, and control the execution flow.
- - -
- Figure 1. The Choose Device window enables you to - select a physical Android device or a virtual device to debug your app.
-To run your app in debug mode, you build an APK signed with a debug key and install it on a -physical Android device or on the Android emulator. -To set up an Android device for development, see Using -Hardware Devices. For more information about the emulator provided by the Android SDK, see -Using the Emulator.
- -To debug your app in Android Studio:
- - in the toolbar.Figure 1 shows the Choose Device window. The list shows all the Android devices
-connected to your computer. Select Launch Emulator to use an Android virtual device
-instead. Click the ellipsis 
to open the
-Android Virtual Device Manager.
Android Studio opens the Debug tool window when you debug your app. To open the
-Debug window manually, click Debug
-
.
-This window shows threads and variables in the Debugger tab, the device status in the
-Console tab, and the system log in the Logcat tab. The Debug tool
-window also provides other debugging tools covered in the following sections.
-Figure 2. The Debug tool window in Android Studio showing -the current thread and the object tree for a variable.
- -You don't always have to restart your app to debug it. To debug an app that -you're already running:
- -
.By default, the debugger shows the device and app process for the current -project, as well as any connected hardware devices or virtual devices on your -computer. Select Show all processes to show all processes on -all devices; the display includes any services that your app created as well as -system processes, for example.
-From the Debugger menu, you can select Java, -Native, or Hybrid. The latter two options are -available only if your project contains some native C or C++ source code.
-The Debug window appears. In this case, notice the two tabs to the -right of the Debug window title: one tab is for debugging native code and the -other for Java code, as indicated by -java.
-
-Separate debugging sessions have separate tabs and different port numbers, -which are displayed in parentheses in the tab.
-The system log shows system messages while you debug your app. These messages include -information from apps running on the device. If you want to use the -system log to debug your app, make sure your code writes log messages and prints the stack -trace for exceptions while your app is in the development phase.
- -To write log messages in your code, use the {@link android.util.Log} class. Log messages -help you understand the execution flow by collecting the system debug output while you interact -with your app. Log messages can tell you what part of your application failed. For more -information about logging, see -Reading and Writing Logs.
- -The following example shows how you might add log messages to determine if previous state -information is available when your activity starts:
- -
-import android.util.Log;
-...
-public class MyActivity extends Activity {
- private static final String TAG = MyActivity.class.getSimpleName();
- ...
- @Override
- public void onCreate(Bundle savedInstanceState) {
- if (savedInstanceState != null) {
- Log.d(TAG, "onCreate() Restoring previous state");
- /* restore state */
- } else {
- Log.d(TAG, "onCreate() No saved state available");
- /* initialize app */
- }
- }
-}
-
-
-During development, your code can also catch exceptions and write the stack trace to the system -log:
- -
-void someOtherMethod() {
- try {
- ...
- } catch (SomeException e) {
- Log.d(TAG, "someOtherMethod()", e);
- }
-}
-
-
-Note: Remove debug log messages and stack trace print calls from
-your code when you are ready to publish your app. You could do this by setting a DEBUG
-flag and placing debug log messages inside conditional statements.
Both the Android DDMS (Dalvik Debug Monitor Server) and the Debug tool windows -show the system log; however, the Android DDMS tool window lets you view only log messages -for a particular process. To view the system log on the Android DDMS tool window:
- -
to open the Android DDMS
- tool window..
-Figure 4. The system log in the Android DDMS tool -window.
- -The Android DDMS tool window gives you access to some DDMS features from Android Studio. -For more information about DDMS, see Using DDMS. -
- -The system log shows messages from Android services and other Android apps. To filter the log -messages to view only the ones you are interested in, use the tools in the Android DDMS -window:
- -
. If the Devices view
- is not available, click Restore Devices View
- 
on the right of the Android
- DDMS tool window. This button is only visible when you hide the Devices
- window.Breakpoints enable you to pause the execution of your app at a particular line of code, examine -variables, evaluate expressions, and continue the execution line by line. Use breakpoints to -determine the causes of run-time errors that you can't fix by looking at your code only. To debug -your app using breakpoints:
- -Android Studio pauses the execution of your app when it reaches the breakpoint. You can then -use the tools in the Debug tool window to identify the cause of the error.
- -
-Figure 5. A red dot appears next to the line when you set -a breakpoint.
- -To view all the breakpoints and configure breakpoint settings, click View
-Breakpoints 
on the left side of the Debug tool
-window. The Breakpoints window appears, as shown in figure 6.
-Figure 6. The Breakpoints window lists all the current -breakpoints and includes behavior settings for each.
- -The Breakpoints window lets you enable or disable each breakpoint from the -list on the left. If a breakpoint is disabled, Android Studio does not pause your app when -it hits that breakpoint. Select a breakpoint from the list to configure its settings. -You can configure a breakpoint to be disabled at first and have the system enable it after a -different breakpoint is hit. You can also configure whether a breakpoint should be disabled after -it is hit. To set a breakpoint for any exception, select Exception Breakpoints -in the list of breakpoints.
- -After you set breakpoints in your code, click Rerun
- to start the app again. When a breakpoint is
-hit, Android Studio pauses the app and highlights the breakpoint in the source code. The
-Debug tool window lets you examine variables and control the execution step by
-step:
To examine the object tree for a variable, expand it in the Variables view. If
- the Variables view is not visible, click Restore Variables View
- 
.
To evaluate an expression at the current execution point, click Evaluate
- Expression 
.
To advance to the next line in the code (without entering a method), click Step
- Over 
.
To advance to the first line inside a method call, click Step
- Into 
.
To advance to the next line outside the current method, click Step
- Out 
.
To continue running the app normally, click Resume Program
- 
.
-Figure 7. The Variables view in the Debug tool window.
- - -Android Studio lets you track objects that are being allocated on the Java heap and see which -classes and threads are allocating these objects. This allows you to see the list of objects -allocated during a period of interest. This information is valuable for assessing memory usage -that can affect application performance.
- -To track memory allocation of objects:
- - to open the Android DDMS
-tool window.
Android Studio shows the objects that the system allocated with the following information:
- -
-Figure 8. Object allocation tracking in Android Studio.
- - -Even if your application does not generate runtime errors, this does not mean it is free of -problems. You should also consider the following issues:
- -The Android Device Monitor is a stand-alone tool with a graphical user interface for serveral -Android application debugging and analysis tools, including the Dalvik Debug Monitor Server (DDMS). -You can use the Android Device Monitor to analyze memory usage, profile methods, -monitor network traffic and simulate incoming calls and messages.
- -To open the Android Device Monitor from Android Studio, click
-Monitor 
on the toolbar. The Android Device Monitor
-opens in a new window.
For more information about the Android Device Monitor and DDMS, see -Device Monitor and -Using DDMS.
- - -Android Studio enables you to capture a screenshot or a short video of the device screen -while your app is running. Screenshots and videos are useful as promotional materials for your -app, and you can also attach them to bug reports that you send to your development team.
- -To take a screenshot of your app:
- - to open the Android DDMS
- tool window.
on the left side of the
- Android DDMS tool window.To take a video recording of your app:
- - to open the Android DDMS
- tool window.
on the left side of the
- Android DDMS tool window.Traceview is a graphical viewer for execution logs that you create by using the {@link - android.os.Debug} class to log tracing information in your code. Traceview can help you debug - your application and profile its performance.
- -When you have a trace log file (generated by adding tracing code to your application or by DDMS), - you can load the log files in Traceview, which displays the log data in two panels:
- -The sections below provide addition information about the traceview output panes.
- -Figure 1 shows a close up of the timeline panel. Each thread’s execution is shown - in its own row, with time increasing to the right. Each method is shown in another color (colors - are reused in a round-robin fashion starting with the methods that have the most inclusive time). - The thin lines underneath the first row show the extent (entry to exit) of all the calls to the - selected method.
- -
- Figure 1. The Traceview Timeline Panel
- -Figure 2 shows the profile pane, a summary of all the time spent
- in a method. The table shows both the inclusive and exclusive times (as well as the percentage of
- the total time). Exclusive time is the time spent in the method. Inclusive time is the time spent
- in the method plus the time spent in any called functions. We refer to calling methods as
- "parents" and called methods as "children." When a method is selected (by clicking on it), it
- expands to show the parents and children. Parents are shown with a purple background and children
- with a yellow background. The last column in the table shows the number of calls to this method
- plus the number of recursive calls. The last column shows the number of calls out of the total
- number of calls made to that method. In this view, we can see that there were 14 calls to
- LoadListener.nativeFinished(); looking at the timeline panel shows that one of those calls took
- an unusually long time.
- Figure 2. The Traceview Profile Panel
- -To use Traceview, you need to generate log files containing the trace information you want to - analyze.
- -There are two ways to generate trace logs:
-Before you start generating trace logs, be aware of the following restrictions:
-This document focuses on using the {@link android.os.Debug} class to generate trace data. For more information on using DDMS - to generate trace data, see Using the Dalvik Debug Monitor Server. -
- -To create the trace files, include the {@link android.os.Debug} class and call one of the - {@link android.os.Debug#startMethodTracing() startMethodTracing()} methods. In the call, you - specify a base name for the trace files that the system generates. To stop tracing, call {@link - android.os.Debug#stopMethodTracing() stopMethodTracing()}. These methods start and stop method - tracing across the entire virtual machine. For example, you could call - {@link android.os.Debug#startMethodTracing() startMethodTracing()} in - your activity's {@link android.app.Activity#onCreate onCreate()} method, and call - {@link android.os.Debug#stopMethodTracing() stopMethodTracing()} in that activity's - {@link android.app.Activity#onDestroy()} method.
-
- // start tracing to "/sdcard/calc.trace"
- Debug.startMethodTracing("calc");
- // ...
- // stop tracing
- Debug.stopMethodTracing();
-
-
- When your application calls {@link android.os.Debug#startMethodTracing() startMethodTracing()},
- the system creates a file called
- <trace-base-name>.trace. This contains the binary method trace data and a
- mapping table with thread and method names.
The system then begins buffering the generated trace data, until your application calls - {@link android.os.Debug#stopMethodTracing() stopMethodTracing()}, at which time it writes - the buffered data to the output file. If the system - reaches the maximum buffer size before you call {@link android.os.Debug#stopMethodTracing() - stopMethodTracing()}, the system stops tracing - and sends a notification to the console.
- -Interpreted code runs more slowly when profiling is enabled. Don't try to generate - absolute timings from the profiler results (such as, "function X takes 2.5 seconds to run"). The - times are only useful in relation to other profile output, so you can see if changes have made - the code faster or slower relative to a previous profiling run.
- -In Android 4.4 and later, you can use sample-based profiling to profile with less runtime - performance impact. To enable sample profiling, call {@link - android.os.Debug#startMethodTracingSampling(java.lang.String, int, int) - startMethodTracingSampling()} with a specified sampling interval. The system will then gather - samples periodically until tracing is stopped via {@link android.os.Debug#stopMethodTracing() - stopMethodTracing()}.
- -After your application has run and the system has created your trace files
- <trace-base-name>.trace on a device or emulator, you must copy those files to
- your development computer. You can use adb pull to copy the files. Here's an example
- that shows how to copy an example file, calc.trace, from the default location on the emulator to
- the /tmp directory on the emulator host machine:
-adb pull /sdcard/calc.trace /tmp -- -
To run Traceview and view the trace files:
-Note: If you are trying to view the trace logs of an application
- that is built with ProGuard enabled (release mode build), some method and member names might be obfuscated.
- You can use the Proguard mapping.txt file to figure out the original unobfuscated names. For more information
- on this file, see the Proguard documentation.
dmtracedump is a tool that gives you an alternate way of generating
- graphical call-stack diagrams from trace log files. The tool uses the Graphviz Dot utility to
- create the graphical output, so you need to install Graphviz before running dmtracedump.
The dmtracedump tool generates the call stack data as a tree diagram, with each call - represented as a node. It shows call flow (from parent node to child nodes) using arrows. The - diagram below shows an example of dmtracedump output.
-Figure 3. Screenshot of dmtracedump
- -For each node, dmtracedump shows <ref>
- callname (<inc-ms>, <exc-ms>,<numcalls>), where
<ref> -- Call reference number, as used in trace logs<inc-ms> -- Inclusive elapsed time (milliseconds spent in method,
- including all child methods)<exc-ms> -- Exclusive elapsed time (milliseconds spent in method,
- not including any child methods)<numcalls> -- Number of callsThe usage for dmtracedump is:
--dmtracedump [-ho] [-s sortable] [-d trace-base-name] [-g outfile] <trace-base-name> -- -
The tool then loads trace log data from <trace-base-name>.data and
- <trace-base-name>.key. The table below lists the options for dmtracedump.
| Option | - -Description | -
|---|---|
-d <trace-base-name> |
-
- Diff with this trace name | -
-g <outfile> |
-
- Generate output to <outfile> | -
-h |
-
- Turn on HTML output | -
-o |
-
- Dump the trace file instead of profiling | -
-d <trace-base-name> |
-
- URL base to the location of the sortable javascript file | -
-t <percent> |
-
- Minimum threshold for including child nodes in the graph (child's inclusive time as a - percentage of parent inclusive time). If this option is not used, the default threshold - is 20%. | -
Sometimes your application's layout can slow down your application.
-To help debug issues in your layout, the Android SDK provides the Hierarchy Viewer and
-lint tools.
The Hierarchy Viewer application allows you to debug and optimize your user interface. It - provides a visual representation of the layout's View hierarchy (the View Hierarchy window) - with performance information for each node in the layout, - and a magnified view of the display (the Pixel Perfect window) to closely examine the pixels - in your layout.
- -Android lint is a static code
- scanning tool that helps you optimize the layouts and layout
- hierarchies of your applications, as well as detect other common coding problems. You can run it
- against your layout files or resource
- directories to quickly check for inefficiencies or other types of problems that could be
- affecting the performance of your application.
- To run Hierarchy Viewer, follow these steps:
-- To preserve security, Hierarchy Viewer can only connect to devices running a - developer version of the Android system. -
-hierarchyviewer from the
- <sdk>/tools/
- directory.
- - To learn how to use the View Hierarchy window, go to - About the View Hierarchy window. To learn how to use the - Pixel Perfect window, go to About the Pixel Perfect window. -
-
-Figure 1. Hierarchy Viewer device window
-- The View Hierarchy window displays the View objects that form the UI of the - Activity that is running on your device or emulator. You use it to look at individual - View objects within the context of the entire View tree. For each View object, the View - Hierarchy window also displays rendering performance data. -
-- To see the View Hierarchy window, run Hierarchy Viewer as described in - the section Running Hierarchy Viewer and choosing a window. Next, click - View Hierarchy at the top of the device window. -
-- You should see four panes: -
-- To zoom in on the pane, use the slider at the bottom of the pane, or use your mouse - scroll wheel. To move around in the pane or reveal View objects that are not currently - visible, click and drag the pane. -
-- To highlight the nodes in the tree whose class or ID match a search string, enter the - string in the Filter by class or id: edit box at the bottom of the - window. The background of nodes that match the search string will change from gray to - bright blue. -
-- To save a screenshot of Tree View to a PNG file, click Save As PNG at - the top of the View Hierarchy window. This displays a dialog in which you can choose - a directory and file name. -
-- To save a layered screenshot of your device or emulator to an Adobe Photoshop (PSD) - file, click Capture Layers at the top of the View Hierarchy window. - This displays a dialog in which you can choose a directory or file name. - Each View in the UI is saved as a separate Photoshop layer. -
-- In Photoshop (or similar program that accepts .psd files), you can hide, show or edit a - layer independently of others. When you save a layered screenshot, you can examine and - modify the image of an individual View object. This helps you experiment with design - changes. -
-- You can also use Tree Overview to move around in the Tree View pane. Click and drag - the shaded rectangle over an area to reveal it in Tree View. -
-- The properties are organized by category. To find an individual property, expand - a category name by clicking the arrow on its left. This reveals all the properties - in that category. -
-- The outline colors of blocks in Layout View provide additional information: -
-- When the UI of the current Activity changes, the View Hierarchy window is not automatically - updated. To update it, click Load View Hierarchy at the top of the window. -
-- Also, the window is not updated if you switch to a new Activity. To update it, start by - clicking the window selection icon in the bottom left-hand corner of the window. This - navigates back to the Window Selection window. From this window, click the Android - component name of the new Activity and then click Load View Hierarchy - at the top of the window. -
-- A screenshot of the View Hierarchy window appears in figure 2. -
-
-Figure 2. The View Hierarchy window
-- Each node in Tree View represents a single View. Some information is always visible. Starting - at the top of the node, you see the following: -
-android:id
- attribute.
- - The colors indicate the following relative performance: -
-- When you select a node, additional information for the View appears in a small window above - the node. When you click one of the nodes, you see the following: -
-- An annotated screenshot of an individual node in the Tree View window appears in figure 3. -
-
-Figure 3. An annotated node in Tree View
-- The View Hierarchy window helps you debug an application by providing a static display - of the UI. The display starts with your application's opening screen. As you step through - your application, the display remains unchanged until you redraw it by invalidating and - then requesting layout for a View. -
-- To redraw a View in the display: -
-- Manually redrawing a View allows you to watch the View object tree and examine the properties of - individual View objects one step at a time as you go through breakpoints in your code. -
-- View Hierarchy also helps you identify slow render performance. You start by looking at the - View nodes with red or yellow performance indicators to identify the slower View objects. As you - step through your application, you can judge if a View is consistently slow or slow only in - certain circumstances. -
-- Remember that slow performance is not necessarily evidence of a problem, especially for - ViewGroup objects. View objects that have more children and more complex View objects render - more slowly. -
-- The View Hierarchy window also helps you find performance issues. Just by looking at the - performance indicators (the dots) for each View node, you can see which View objects are the - slowest to measure, layout, and draw. From that, you can quickly identify the problems you - should look at first. -
-- Pixel Perfect is a tool for examining pixel properties and laying out UIs from a design drawing. -
-- The Pixel Perfect window displays a magnified image of the screen that is currently - visible on the emulator or device. In it, you can examine the properties - of individual pixels in the screen image. You can also use the Pixel Perfect window - to help you lay out your application UI based on a bitmap design. -
-- To see the Pixel Perfect window, run Hierarchy Viewer, as described in - the section Running Hierarchy Viewer and choosing a window. Next, click - Inspect Screenshot at the top of the device window. The Pixel Perfect window - appears. -
-- In it, you see three panes: -
-- The magenta crosshair in the pane corresponds to the positioning - crosshair in the next pane. It only moves when you move the crosshair in the next pane. -
-- To zoom in or out on the image, use the Zoom slider at the bottom of - the pane, or use your mouse's scroll wheel. -
-- When you select a pixel in the Loupe pane, you see the following information at the - bottom of the pane: -
-- You use the cyan crosshair to do coarse positioning. Drag the crosshair in the image, - and the Loupe crosshair will move accordingly. You can also click on a point in the - Pixel Perfect pane, and the crosshair will move to that point. -
-- The image corresponding to the View object selected in the View Object pane is - outlined in a box that indicates the View object's position on the screen. For the - selected object, the box is bold red. Sibling and parent View objects have a light - red box. View objects that are neither parents nor siblings are in white. -
-- The layout box may have other rectangles either inside or outside it, each of which - indicates part of the View. A purple or green rectangle indicates the View bounding box. - A white or black box inside the layout box represents the padding, the - defined distance between the View object's content and its bounding box. An outer white - or black rectangle represents the margins, the distance between the - View bounding box and adjacent View objects. The padding and margin boxes are white if - the layout background is black, and vice versa. -
-- You can save the screen image being displayed in the Pixel Perfect pane as a PNG file. - This produces a screenshot of the current screen. To do this, click - Save as PNG at the top of the window. This displays a dialog, - in which you can choose a directory and filename for the file. -
-- The panes are not automatically refreshed when you change one of the View objects or go to - another Activity. To refresh the Pixel Perfect pane and the Loupe pane, click - Refresh Screenshot at the top of the window. This will change the panes - to reflect the current screen image. You still may need to refresh the View Object pane; - to do this, click Refresh Tree at the top of the window. -
-- To automatically refresh the panes while you are debugging, set - Auto Refresh at the top of the window, and then set a refresh rate - with the Refresh Rate slider at the bottom of the Loupe pane. -
-- You often construct a UI based on a design done as a bitmap image. The Pixel Perfect window - helps you match up your View layout to a bitmap image by allowing you to load the bitmap as an - overlay on the screen image. -
-- To use a bitmap image as an overlay: -
-- By default, the overlay has a 50% transparency, which allows you to see the screen - image underneath. You can adjust this with the Overlay: slider at the - bottom of the Loupe pane. -
-- Also by default, the overlay is not displayed in the Loupe pane. To display it, - set Show in Loupe at the top of the window. -
-- The overlay is not saved as part of the screenshot when you save the screen image as a PNG - file. -
-- A screenshot of the Pixel Perfect window appears in figure 4. -
-
-Figure 4. The Pixel Perfect window
- - -The Android lint tool lets you analyze the XML -files that define your application's UI to find inefficiencies in the view hierarchy.
-Note: The Android layoutopt tool has been replaced by the {@code lint} tool beginning in SDK Tools revision 16. The {@code lint} tool reports UI layout performance issues in a similar way as layoutopt, and detects additional problems.
For more information about using {@code lint}, see Improving Your Code with lint and the lint tools help.
diff --git a/docs/html/tools/debugging/improving-w-lint.jd b/docs/html/tools/debugging/improving-w-lint.jd deleted file mode 100644 index 2f5e50d5a5ef96c292b201a7a2796cadf0b001d5..0000000000000000000000000000000000000000 --- a/docs/html/tools/debugging/improving-w-lint.jd +++ /dev/null @@ -1,343 +0,0 @@ -page.title=Improving Your Code with lint -parent.title=Debugging -parent.link=index.html -@jd:body - --In addition to testing that your Android application meets its functional requirements, it's -important to ensure that your code has no structural problems. Poorly structured code can impact the -reliability and efficiency of your Android apps and make your code harder to maintain. For example, -if your XML resource files contain unused namespaces, this takes up space and incurs unnecessary -processing. Other structural issues, such as use of deprecated elements or API calls that are not -supported by the target API versions, might lead to code failing to run correctly.
- -The Android SDK provides a code scanning tool called lint
-that can help you to easily identify and correct problems with the structural quality of your code,
-without having to execute the app or write any test cases. Each problem detected by the tool is
-reported with a description message and a severity level, so that you can quickly prioritize the
-critical improvements that need to be made. You can also configure a problem's severity level to
-ignore issues that are not relevant for your project, or raise the severity level. The tool has a
-command-line interface, so you can easily integrate it into your automated testing process.
The {@code lint} tool checks your Android project source files for potential bugs and -optimization improvements for correctness, security, performance, usability, accessibility, and -internationalization. You can run {@code lint} from the command-line or from Android Studio.
- -Note: In Android Studio, additional -IntelliJ code inspections run when your code is compiled in Android Studio to -streamline code review.
- -Figure 1 shows how the {@code lint} tool processes the application source files.
-
-Figure 1. Code scanning workflow with the {@code lint} tool
-lint.xml fileThe {@code lint} tool is automatically installed as part of the Android SDK Tools revision 16 or -higher.
- - -In Android Studio, the configured lint and
-IDE inspections run automatically whenever you build your app. The IDE inspections are
-configured along with the {@code lint} checks to run
-IntelliJ code inspections to streamline code review.
Note: To view and modify inspection severity -levels, use the File > Settings > Project Settings menu to open the -Inspection Configuration page with a list of the supported inspections.
- - -With Android Studio, you can also run {@code lint} inspections for a specific build variant,
-or for all build variants from the build.gradle file. Add the
-lintOptions property to the android settings in the build file.
-This code snippet from a Gradle build file shows how to set the quiet option to
-true and the abortOnError option to false.
-android {
- lintOptions {
- // set to true to turn off analysis progress reporting by lint
- quiet true
- // if true, stop the gradle build if errors are found
- abortOnError false
- // if true, only report errors
- ignoreWarnings true
- }
- ...
- }
-
-
-
-To manually run inspections in Android Studio, from the application or right-click menu, -choose Analyze > Inspect Code. The Specify Inspections Scope dialog -appears so you can specify the desired inspection scope and profile.
- - - - --To run {@code lint} against a list of files in a project directory: -
lint [flags] <project directory>-
For example, you can issue the following command to scan the files under the {@code myproject}
-directory and its subdirectories. The issue ID MissingPrefix tells {@code lint} to
-only scan for XML attributes that are missing the Android namespace prefix.
lint --check MissingPrefix myproject-
To see the full list of flags and command-line arguments supported by the tool:
-lint --help- - -
The following example shows the console output when the {@code lint} command is run against a -project called Earthquake.
--$ lint Earthquake - -Scanning Earthquake: ............................................................................................................................... -Scanning Earthquake (Phase 2): ....... -AndroidManifest.xml:23: Warning: <uses-sdk> tag appears after <application> tag [ManifestOrder] - <uses-sdk android:minSdkVersion="7" /> - ^ -AndroidManifest.xml:23: Warning: <uses-sdk> tag should specify a target API level (the highest verified version; when running on later versions, compatibility behaviors may be enabled) with android:targetSdkVersion="?" [UsesMinSdkAttributes] - <uses-sdk android:minSdkVersion="7" /> - ^ -res/layout/preferences.xml: Warning: The resource R.layout.preferences appears to be unused [UnusedResources] -res: Warning: Missing density variation folders in res: drawable-xhdpi [IconMissingDensityFolder] -0 errors, 4 warnings --
The output above lists four warnings and no errors in this project. Three warnings
-({@code ManifestOrder}, {@code UsesMinSdkAttributes}, and {@code UnusedResources}) were found in
-the project's AndroidManifest.xml file. The remaining warning
-({@code IconMissingDensityFolder}) was found in the Preferences.xml layout file.
By default, when you run a {@code lint} scan, the tool checks for all issues that are supported -by {@code lint}. You can also restrict the issues for {@code lint} to check and assign the severity -level for those issues. For example, you can disable {@code lint} checking for specific issues that -are not relevant to your project and configure {@code lint} to report non-critical issues at a lower -severity level.
-You can configure {@code lint} checking at different levels:
-The built-in Lint tool checks your code while you're using -Android Studio. You can view warnings and errors in two ways:
-To set default Lint checks:
-You can select individual checks, or entire categories.
- -To produce a list of Lint checks displayed in the Inspection Results -window:
-The scope specifies the files you want to analyze, and the profile specifies -the Lint checks you’d like to perform.
-In the Inspections dialog, you can search for a string -to find Lint checks. Note that changing Lint settings for a -profile in the Inspections dialog doesn’t change the default settings, -as described in the previous procedure. It does change the settings for profiles -displayed in the Inspections dialog, however.
-The results appear in the Inspection Results window, organized by -category.
- -You can specify your {@code lint} checking preferences in the lint.xml file. If you
-are creating this file manually, place it in the root directory of your Android project. If you are
-configuring {@code lint} preferences in Android Studio, the lint.xml file is
-automatically created and added to your Android project for you.
The lint.xml file consists of an enclosing <lint> parent tag that
-contains one or more children <issue> elements. Each <issue>
-is identified by a unique id attribute value, which is defined by {@code lint}.
-<?xml version="1.0" encoding="UTF-8"?> - <lint> - <!-- list of issues to configure --> -</lint> --
By setting the severity attribute value in the <issue> tag, you can disable
-{@code lint} checking for an issue or change the severity level for an issue.
Tip: To see the full list of issues supported by the {@code lint}
-tool and their corresponding issue IDs, run the lint --list command.
The following example shows the contents of a lint.xml file.
-<?xml version="1.0" encoding="UTF-8"?> -<lint> - <!-- Disable the given check in this project --> - <issue id="IconMissingDensityFolder" severity="ignore" /> - - <!-- Ignore the ObsoleteLayoutParam issue in the specified files --> - <issue id="ObsoleteLayoutParam"> - <ignore path="res/layout/activation.xml" /> - <ignore path="res/layout-xlarge/activation.xml" /> - </issue> - - <!-- Ignore the UselessLeaf issue in the specified file --> - <issue id="UselessLeaf"> - <ignore path="res/layout/main.xml" /> - </issue> - - <!-- Change the severity of hardcoded strings to "error" --> - <issue id="HardcodedText" severity="error" /> -</lint> -- -
You can disable {@code lint} checking from your Java and XML source files.
- -Tip: If you are using Android Studio, you can use the -File > Settings > Project Settings > Inspections feature to manage the -{@code lint} checking to your Java or XML source files. -
- -To disable {@code lint} checking specifically for a Java class or method in your Android project,
-add the @SuppressLint annotation to that Java code.
The following example shows how you can turn off {@code lint} checking for the {@code NewApi}
-issue in the onCreate method. The {@code lint} tool continues to check for the
-{@code NewApi} issue in other methods of this class.
-@SuppressLint("NewApi")
-@Override
-public void onCreate(Bundle savedInstanceState) {
- super.onCreate(savedInstanceState);
- setContentView(R.layout.main);
-
-The following example shows how to turn off {@code lint} checking for the {@code ParserError}
-issue in the FeedProvider class:
-@SuppressLint("ParserError")
-public class FeedProvider extends ContentProvider {
-
-To suppress checking for all {@code lint} issues in the Java file, use the {@code all} keyword, -like this:
-
-@SuppressLint("all")
-
-
-You can use the tools:ignore attribute to disable {@code lint} checking for specific
-sections of your XML files. In order for this attribute to be recognized by the {@code lint} tool,
-the following namespace value must be included in your XML file:
-namespace xmlns:tools="http://schemas.android.com/tools" --
The following example shows how you can turn off {@code lint} checking for the
-{@code UnusedResources} issue for the <LinearLayout> element of an XML layout
-file. The ignore attribute is inherited by the children elements of the parent element
-in which the attribute is declared. In this example, the {@code lint} check is also disabled for the
-child <TextView> element.
-<LinearLayout - xmlns:android="http://schemas.android.com/apk/res/android" - xmlns:tools="http://schemas.android.com/tools" - tools:ignore="UnusedResources" > - - <TextView - android:text="@string/auto_update_prompt" /> -</LinearLayout> --
To disable more than one issue, list the issues to disable in a comma-separated string. For -example:
--tools:ignore="NewApi,StringFormatInvalid" --
To suppress checking for all {@code lint} issues in the XML element, use the {@code all} keyword, -like this:
--tools:ignore="all" -diff --git a/docs/html/tools/debugging/index.jd b/docs/html/tools/debugging/index.jd deleted file mode 100644 index 97179169f97244dfdb48380e70a097d428cbd910..0000000000000000000000000000000000000000 --- a/docs/html/tools/debugging/index.jd +++ /dev/null @@ -1,185 +0,0 @@ -page.title=Debugging -@jd:body - - -
The Android SDK provides most of the tools that you need to debug your applications. You need - a JDWP-compliant debugger if you want to be able to do things such as step through code, - view variable values, and pause execution of an application. If you are using Android Studio, a - JDWP-compliant debugger is already included and there is no setup required. If you are using - another IDE, you can use the debugger that comes with it and attach the debugger to a special - port so it can communicate with the application VMs on your devices. The main components that - comprise a typical Android debugging environment are:
- -adb acts as a middleman between a device and your development system. It
- provides various
- device management capabilities, including moving and syncing files to the emulator, running a
- UNIX shell on the device or emulator, and providing a general means to communicate with
- connected emulators and devices.adb. DDMS can
- capture screenshots, gather thread and stack information, spoof incoming calls and SMS
- messages, and has many other features.adb device daemon runs on the device or emulator and provides a means for the
- adb host daemon to communicate with the device or emulator.jdb.Figure 1 shows how the various debugging tools work together in a typical - debugging environment.
-
- In addition to the main debugging tools, the Android SDK provides additional tools to help you - debug and profile your applications:
- -While debugging, keep these helpful tips in mind to help you figure out common problems with your -applications:
- -adb shell, use ps to find the process you
-want, and then kill -3. The stack trace appears in the log file.
-adb shell commands. See
-dumpsys and
-dumpstate on the adb topic page.-adb shell -logcat -b radio --
While developing your application, you should check that user interactions are buttery smooth, -running at a consistent 60 frames per second. If something goes wrong, and a frame gets dropped, the -first step in fixing the problem is understanding what the system is doing.
- -The Systrace tool allows you to collect and inspect timing information across an entire Android -device, which is called a trace. It shows where time and CPU cycles are being spent, -displaying what each thread and process is doing at any given time. It also inpects the captured -tracing information to highlight problems that it observes, from list item recycling to rendering -content, and provide recommendations about how to fix them. This document explains how to navigate -the trace files produced by the tool, and use them to analyze the performance of an application's -user interface (UI).
- -Systrace helps you analyze how the execution of your application fits into the many running -systems on an Android device. It puts together system and application thread execution on a common -timeline. In order to analyze your app with Systrace, you first collect a trace log of your app, and -the system activity. The generated trace allows you to view highly detailed, interactive reports -showing everything happening in the system for the traced duration.
- -
-- Figure 1. An example Systrace, showing 5 seconds of scrolling an app when it - is not performing well. -
- -Figure 1. shows a trace captured while scrolling an app that is not rendering smoothly. By -default, a zoomed out view of the traced duration is shown. The horizontal axis is time, and trace -events are grouped by process, and then by thread on the vertical axis.
- -The groupings are in the order Kernel, SurfaceFlinger (the android compositor process), followed -by apps, each labeled by package name. Each app process contains all of the tracing signals from -each thread it contains, including a hierarchy of high level tracing events based on the enabled -tracing categories.
- - -In order to create a trace of your application, you must perform a few setup steps. First, you -must have a device running Android 4.1 (API 16) or higher. Set up the device -for debugging, connect it to your development -system, and install your application. Some types of trace information, specifically disk activity -and kernel work queues, require that you have root access to the device. However, most Systrace log -data only requires that the device be enabled for developer debugging.
- -Systrace traces can be run either from -a command line or from a -graphical user interface. This guide focuses on -using the command line options.
- -To run a trace on Android 4.3 and higher devices:
- --$ cd android-sdk/platform-tools/systrace -$ python systrace.py --time=10 -o mynewtrace.html sched gfx view wm --
For more information on the available options for running Systrace, see the -Systrace help page.
- - -To use Systrace effectively with devices running Android 4.2 and lower, - you must configure the types of processes you want to trace before running a trace. - The tool can gather the following types of process information:
- -To set trace tags for Systrace using the command-line:
- --$ cd android-sdk/platform-tools/systrace -$ python systrace.py --set-tags=gfx,view,wm --
-$ adb shell stop -$ adb shell start -
To set trace tags for Systrace using the device user interface:
- -- Note: The {@code adb} shell does not have to be stopped and restarted when - selecting trace tags using this method. -
- -After you have configured the category tags for your trace, you can start collecting - information for analysis.
- -To run a trace using the current trace tag settings:
- --$ python systrace.py --cpu-freq --cpu-load --time=10 -o mytracefile.html --
For more information on the available options for running Systrace, see the -Systrace help page.
- - -After you have generated a trace, open the output html file using a web browser. This section -explains how to analyze and interpret the information that the tool produces to find and fix UI -performance problems.
- -Each app that is rendering frames shows a row of frame circles, which are typically colored -green. Circles that are colored yellow or red, exceeding the 16.6 millisecond run time limit -required to maintain a stable 60 frames per second. Zoom in using the 'w' key to see the frames of -your application, and look for long-running frames getting in the way of smoothness.
- -- Note: Hit the '?' key, or the button in the top right for help navigating the - trace. -
- -
-- Figure 2. Systrace display after zooming in on a long-running frame. -
- -Clicking on one such frame highlights it, focusing only on the work done by the system for that -frame. On devices running Android 5.0 (API level 21) or higher, this work is split between the UI -Thread and RenderThread. On prior versions, all work in creating a frame is done on the UI -Thread.
- -Click on individual components of the frame to see how long they took to run. Some events, such -as performTraversals, describe what the system is doing in that method when you select -it. Selecting a frame displays any alerts present in that frame.
- -Systrace does automatic analysis of the events in the trace, and highlights many performance -problems as alerts, suggesting what to do next.
- -
-- Figure 3. Selecting the problematic frame, an alert is shown identifying a problem. -
- -After you select a slow frame such as the one shown in Figure 3, an alert may be displayed. In -the case above, it calls out that the primary problem with the frame is too much work being done -inside {@link android.widget.ListView} recycling and rebinding. There are links to the relevant -events in the trace, which can be followed to explain more about what the system is doing during -this time.
- -If you see too much work being done on the UI thread, as in this case with this -{@link android.widget.ListView} work, you can -use Traceview, the app code profiling -tool, to investigate exactly what is taking so much time.
- -Note that you can also find about every alert in the trace by clicking the Alerts tab to -the far right of the window. Doing so expands the Alerts panel, where you can see every alert that -the tool discovered in your trace, along with an occurrence count.
- -
-- Figure 4. Clicking the Alert button to the right reveals the alert tab. -
- -The Alerts panel helps you see which problems occur in the trace, and how often they contribute -to jank. Think of the alerts panel as a list of bugs to be fixed, often a tiny change or improvement -in one area can eliminate an entire class of alerts from your application!
- - -The tracing signals defined by the framework do not have visibility into everything your -application is doing, so you may want to add your own. In Android 4.3 (API level 18) and higher, you -can use the methods of the {@link android.os.Trace} class to add signals to your code. This -technique can help you see what work your application's threads are doing at any given time. Tracing -begin and end events do add overhead while a trace is being captured, a few microseconds each, but -sprinkling in a few per frame, or per worker thread task can go a long way to adding context to a -trace of your app.
- -The following code example shows how to use the {@link android.os.Trace} class to track -execution of an application method, including two nested code blocks within that method.
- -
-public void ProcessPeople() {
- Trace.beginSection("ProcessPeople");
- try {
- Trace.beginSection("Processing Jane");
- try {
- // code for Jane task...
- } finally {
- Trace.endSection(); // ends "Processing Jane"
- }
-
- Trace.beginSection("Processing John");
- try {
- // code for John task...
- } finally {
- Trace.endSection(); // ends "Processing John"
- }
- } finally {
- Trace.endSection(); // ends "ProcessPeople"
- }
-}
-
-
-
-- Note: When you nest trace calls within each other, the - {@link android.os.Trace#endSection} method ends the most recently called - {@link android.os.Trace#beginSection} method. This means that a trace started within another - trace cannot extend beyond the end of the enclosing trace, so make sure your beginning and - ending method calls are properly matched to measure your applications processing. -
- -- Note: Traces must begin and end on the same thread. Do not call - {@link android.os.Trace#beginSection} on one thread of execution and then attempt to end the - trace with a call to {@link android.os.Trace#endSection} on another thread. -
- -When using application-level tracing with Systrace, you must specify the package name of your -application in the user interface or specify the {@code -a} or {@code --app=} options on the -command line. For more information, see the -Systrace usage guide.
- -You should enable app level tracing when profiling your app, even if you have not added signals -yourself. Library code can include very useful tracing signals when you enable application-level -tracing. The {@link android.support.v7.widget.RecyclerView} class is a great example of this, -providing information about several important stages of work it executes.
- diff --git a/docs/html/tools/device.jd b/docs/html/tools/device.jd deleted file mode 100644 index 2f39402db064cf7e71673a12f48783d424fd3725..0000000000000000000000000000000000000000 --- a/docs/html/tools/device.jd +++ /dev/null @@ -1,329 +0,0 @@ -page.title=Using Hardware Devices -@jd:body - -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.
- -If you want a SIM-unlocked phone, then you might consider a Nexus phone. To purchase a -Nexus phone, visit the Google Play store.
- -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.
- - -
-
-Android-powered devices have a host of developer options that you can -access on the phone, which let you:
-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.
- - - - -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:
- -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
- }
-
-
- 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).
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.
-udev rules file that contains a USB configuration for each type of device
-you want to use for development. In the rules file, each device manufacturer
-is identified by a unique vendor ID, as specified by the
-ATTR{idVendor} property. For a list of vendor IDs, see USB Vendor IDs, below. To set up device detection on
-Ubuntu Linux:
-
- /etc/udev/rules.d/51-android.rules.
- Use this format to add each vendor to the file:
- SUBSYSTEM=="usb", ATTR{idVendor}=="0bb4", MODE="0666", GROUP="plugdev"
-
-
- In this example, the vendor ID is for HTC. The MODE
-assignment specifies read/write permissions, and GROUP defines
-which Unix group owns the device node.
Note: The rule syntax
-may vary slightly depending on your environment. Consult the udev
-documentation for your system as needed. For an overview of rule syntax, see
-this guide to writing udev
-rules.
chmod a+r /etc/udev/rules.d/51-android.rules
- 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.
- - -When plugged in over USB, you can verify that your device is connected by executing adb
-devices from your SDK {@code 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.
This table provides a reference to the vendor IDs needed in order to add USB
-device support on Linux. The USB Vendor ID is the value given to the
-ATTR{idVendor} property in the rules file, as described
-above.
| Company | USB Vendor ID |
|---|---|
| Acer | -0502 |
-
| ASUS | -0b05 |
-
| Dell | -413c |
-
| Foxconn | -0489 |
-
| Fujitsu | -04c5 |
-
| Fujitsu Toshiba | -04c5 |
-
| Garmin-Asus | -091e |
-
18d1 |
- |
| Haier | -201E |
-
| Hisense | -109b |
-
| HP | -03f0 |
-
| HTC | -0bb4 |
-
| Huawei | -12d1 |
-
| Intel | -8087 |
-
| K-Touch | -24e3 |
-
| KT Tech | -2116 |
-
| Kyocera | -0482 |
-
| Lenovo | -17ef |
-
| LG | -1004 |
-
| Motorola | -22b8 |
-
| MTK | -0e8d |
-
| NEC | -0409 |
-
| Nook | -2080 |
-
| Nvidia | -0955 |
-
| OTGV | -2257 |
-
| Pantech | -10a9 |
-
| Pegatron | -1d4d |
-
| Philips | -0471 |
-
| PMC-Sierra | -04da |
-
| Qualcomm | -05c6 |
-
| SK Telesys | -1f53 |
-
| Samsung | -04e8 |
-
| Sharp | -04dd |
-
| Sony | -054c |
-
| Sony Ericsson | -0fce |
-
| Sony Mobile Communications | -0fce |
-
| Teleepoch | -2340 |
-
| Toshiba | -0930 |
-
| ZTE | -19d2 |
-
The Android Emulator simulates a device and displays it on your development -computer. It lets you prototype, develop, and test -Android apps without using a hardware device. The emulator supports Android -phone, tablet, Android Wear, and Android TV devices. It comes with predefined -device types -so you can get started quickly, and you can create your own device definitions -and emulator skins.
- -The Android Emulator is fast, -powerful, and feature-rich. It can transfer information faster than using -a connected hardware device, speeding up the development process. The -multi-core feature lets the emulator take advantage of multiple core -processors on your development computer to improve emulator performance even -more.
- -
-
-You can launch an app on the emulator when you run your project, or you can -drag an APK file onto the emulator to install it. As with a hardware device, -after you install an app -on a virual device, it remains until you uninstall or replace it. If needed, you -can test how multiple apps, such as your own or system apps, work with each -other.
- -You interact with the emulator just as you would with a hardware device, but -using your mouse and keyboard, and emulator buttons and controls. -The emulator supports virtual hardware buttons and touchscreens, including -two-finger operations, -as well as directional pads (D-pads), trackballs, wheels, and various -sensors. You can dynamically resize the emulator window as needed, zoom in and -out, change the orientation, and even take a screenshot.
- -When your app is running on -the emulator, it can use the services of the Android platform to invoke other -apps, access the network, play audio and video, accept audio input, -store and retrieve data, notify the user, and render graphical transitions and -themes. The emulator has controls that let -you easily send incoming phone calls and text messages, specify -the location of the device, simulate fingerprint scans, specify network -speed and status, and simulate battery properties. The emulator can -simulate an SD card and internal data storage; you can drag a file, such as a -graphics or data file, onto the emulator to store it.
- -The emulator uses an Android Virtual Device (AVD) configuration to determine -the look, functionality, and system image of the simulated device. AVDs let you -define certain hardware aspects of your emulated devices and allow you to create -many configurations to test different Android platforms and hardware -permutations.
- -Each AVD functions as an independent device, with its own private storage for -user data, SD card, and so on. When you launch the emulator with an AVD -configuration, it automatically loads the user data and SD card data from the -AVD directory. By default, the emulator stores the user data, SD card data, and -cache in the AVD directory.
- -To create and manage AVDs, use the -AVD Manager. -For more information, see -Managing Virtual Devices.
- -The Android Emulator runs a full -Android system stack, down to the kernel level, that includes a set of -preinstalled apps (such as the dialer) that you can access from your -apps. You can choose which version of the Android system you want to -run in the emulator when creating AVDs. -
- -The Android system images available through the AVD Manager contain -code for the Android Linux kernel, the native libraries, the VM, and the -various Android packages (such as the Android framework and preinstalled -apps).
- -The Android Emulator has the following requirements:
-The Android Emulator supports most features of a device, but doesn't -include virtual hardware for:
-The watch emulator for Android Wear doesn't support the Overview -(Recent Apps) button, D-pad, and fingerprint sensor.
- -While most end users of phones and tablets tend to use earlier API levels, -Android Wear and Android TV users tend to use the latest releases. Using recent -releases can give you a better experience using the emulator. -
- -You can run an app from an Android Studio project. Or, you can run an app -that's been installed on the emulator as you would run any app on a device.
- -To start the emulator and run an app in your project:
-
.The Select Deployment Target dialog appears.
-
-The No USB devices or running emulators detected warning -means that you don’t currently have any emulators running, or any detected -hardware devices connected to your computer. If you -don’t have hardware devices connected to your computer, or any emulators -running, you can ignore it.
-Some errors you must fix before you can continue, such as certain Hardware -Accelerated Execution Manager (Intel® HAXM) errors.
-If you don’t see a definition you want to use, click Create New -Emulator to launch the AVD Manager. After you define a new AVD, in -the Select Deployment -Target dialog, click OK.
-If you want to use this emulator definition as the default for your project, -select Use same selection for future launches.
-The emulator launches and displays your app.
-You can use the features described in the following sections:
-
.The emulator device stores the installed app so you can run it again, if - needed. You need to uninstall an app to remove it. If you run the project - again on the same emulator, it replaces the app with the new version.
-To start the emulator:
-.The Android Emulator appears.
-While the emulator is running, you can run Android Studio projects and - choose the - emulator as the target device. You can also drag one or more APKs onto the - emulator to install them, and then run them.
-Use your computer mouse pointer to mimic your finger on the touchscreen; -select menu items and input fields; and click buttons and controls. -Use your computer keyboard to type characters and enter emulator shortcuts.
-| Feature | -Description | -
|---|---|
| Swipe the screen | -Point to the screen, press and hold the primary mouse button, swipe - across the screen, and then release. | -
| Drag an item | -Point to an item on the screen, press and hold the primary mouse - button, move the item, and then release. | -
| Tap (touch) |
- Point to the screen, press the primary mouse button, and then release. - For example, you could click a text field to start typing in it, select an - app, or press a button. | -
| Double tap | -Point to the screen, press the primary mouse button quickly twice, - and then release. | -
| Touch and hold | -Point to an item on the screen, press the primary mouse button, hold, - and then release. For example, you could open options for an item. | -
| Type | -You can type in the emulator by using your computer keyboard, or using - a keyboard that pops up on the emulator screen. For example, you could - type in a text field after you selected it. | -
Pressing Ctrl or Command (⌘) brings up a pinch gesture multi-touch
- interface. The mouse acts as the first finger, and across the anchor point
- is the second finger. Drag the cursor to move the first point.
- Clicking the left mouse button acts like touching down both points, and
- releasing acts like picking both up. |
-
The panel on the right side of the emulator lets you perform various tasks. -You can also drag files onto the emulator to install apps and download files. -
-| Feature | -Description | -Keyboard Shortcut | -
|---|---|---|
| Close |
- Close the emulator. | -- |
Minimize |
- Minimize the emulator window. | -- |
| Resize | -Resize the emulator as you would any other operating system window. The -emulator maintains an aspect ratio appropriate for your device. | -⌘↑ and ⌘↓ | -
Power |
- Click to turn the screen on or off. Click and hold to turn the device - on or off. |
- Ctrl+P ⌘P |
-
Volume Up |
- Click to view a slider control and turn the volume up. Click again to - turn it up more, or use the slider control to change the volume. | -Ctrl+= ⌘= |
-
Volume Down |
- Click to view a slider control and turn the volume down. Click again to - turn it down more, or use the slider control to change the volume. | -Ctrl+- ⌘- |
-
Rotate Left |
- Rotate the phone 90 degrees counterclockwise. | -Ctrl+Left ⌘← |
-
Rotate Right |
- Rotate the phone 90 degrees clockwise. | -Ctrl+Right ⌘→ |
-
Take Screenshot
- |
- Click to take a screenshot of the device. The default save location is
- your computer desktop. To change the save location, select
- … > Settings. The emulator creates a
- file with the name Screenshot_yyyymmdd-hhmmss.png
- using the year, month, day, hour, minute, and second of the capture, for
- example, Screenshot_20160219-145848.png. |
- Ctrl+S ⌘S |
-
- |
- Click so the cursor changes to the zoom icon: -
Click Enter Zoom Mode again to return to normal screen size. |
- Ctrl+Z ⌘Z
- While in zoom mode:
- Ctrl+Up Ctrl+Down
- Ctrl+Shift+Up Ctrl+Shift+Down
- Ctrl+Shift+Left Ctrl+Shift+Right
- ⌘↑ and ⌘↓
- ⇧⌘↑ and ⇧⌘↓
- ⇧⌘← and ⇧⌘→ |
-
Back |
- Return to the previous screen, or close a dialog box, an options menu, - the Notifications panel, or the onscreen keyboard. | -Ctrl+Backspace
- ⌘⌫ |
-
Home |
- Return to the Home screen. Press and hold to open the item specific to - your API level. | -Ctrl+H ⌘⇧H |
-
Overview
-  (Recent Apps) |
- Tap to open a list of thumbnail images of apps you’ve worked with - recently. To open an app, tap it. To remove a thumbnail from the list, - swipe it left or right. This button isn't supported for Android Wear. | -Ctrl+O ⌘O |
-
| Menu | -Type the keyboard shortcut to simulate the Menu button, for example, - to open the menu for the selected app. | -Ctrl+M ⌘M |
-
More |
- Click to access other features and settings, described in the next - table. | -- |
| Install an APK | -Drag an APK file onto the emulator screen. An APK Installer dialog - appears. When the installation completes, you can view the app in your - apps list.The app didn’t install if a dialog appears that says “APK failed - to install.” | -- |
| Add a file | -Drag any file onto the emulator screen. It’s placed in the
- /sdcard/Download directory. Navigate to the file using the
- method for the API level. For example, for API 22, this is the navigation
- path: Settings > Device: Storage & USB
- > Internal Storage > Explore
- (Virtual SD Card). |
- - |
| Toggle trackball mode | -- | F6 | -
The extended controls let you send data, change device properties, control -apps, and more. To access the controls, select … in the -emulator panel and then select the option you want in the left panel of the -Extended Controls dialog.
- -| Feature | -Description | -Keyboard Shortcuts | -
|---|---|---|
| Location | -
- The emulator lets you simulate “my location” information: the location where
-the emulated device is currently located. For example, if you click My Location
- To send a GPS location: -
In decimal mode, enter a Latitude value in the range -90.0 -to +90.0 degrees and a Longitude value in the range -180.0 to -+180.0 degrees. -In sexigesimal mode, enter a three-part Latitude value in -the range -90 to +90 degrees, 0 to 59 minutes, and 0.0 to 60.0 -seconds. Enter a Longitude value in the range -180 to +180 -degrees, 0 to 59 minutes, and 0.0 to 60.0 seconds. -For the latitude, - indicates south and + indicates north; for the longitude, -- indicates west and + indicates east. The + is optional. -Optionally specify an Altitude value in the range --1,000.0 to +10,000.0 meters. - -To use geographic data from a GPS exchange format (GPX) or Keyhole Markup -Language (KML) file: -
The speed defaults to the Delay value (Speed -1X). You can increase the speed by double (Speed -2X), triple (Speed 3X), and so on. - - |
- Ctrl+Shift+L ⇧⌘L |
-
| Cellular | -The emulator lets you simulate various network conditions. You can - approximate the network speed for different network protocols, or you can - specify Full, which transfers data as quickly as your - computer allows. Specifying a network protocol is always slower than - Full. You can also specify the voice and data network - status, such as roaming. The defaults are set in the AVD. -Select a Network type: -
Select a Voice status, Data status, or -both: -
|
- Ctrl+Shift+C ⇧⌘C |
-
| Battery | -You can simulate the battery properties of a device to see how your - app performs under different conditions. To select a Charge - level, use the slider control. -Select a Charger connection value: -
Select a Battery health value: -
Select a Battery status value: -
|
- Ctrl+Shift+B ⇧⌘B |
-
| Phone | -The emulator lets you simulate incoming phone calls and text - messages. Note that the information flow is one way, from the control to - the emulator. For example, the control doesn’t change its state if the - emulator hangs up; you need to end the call in the control. -To initiate a call to the emulator: -
To send a text message to the emulator: -
|
- Ctrl+Shift+P ⇧⌘P |
-
| Directional Pad | -If the AVD has the directional pad enabled in the hardware profile, - you can use the directional pad controls with the emulator. However, not - all devices can support the directional pad; for example, an Android watch. - The buttons simulate the following actions: -
- |
- Ctrl+Shift+D ⇧⌘D |
-
| Fingerprint | -This control can simulate 10 different fingerprint scans. You can - use it to test fingerprint integration in your app. This feature isn't - supported for Android Wear. -To simulate a fingerprint scan on the virtual device: -
|
- Ctrl+Shift+F ⇧⌘F |
-
| Settings | -You can specify the following settings: -
|
- Ctrl+Shift+S ⇧⌘S |
-
| Help > Keyboard Shortcuts | -See the keyboard shortcuts that the emulator accepts. For the - shortcuts to work, you need to: -
|
- F1 ⌘/ |
-
| Help > Emulator Help | -To go to the online documentation for the emulator, click - Documentation. -To file a bug against the emulator, click File a Bug. - -To make suggestions, click Send Feedback. -All of these links require an internet connection and a browser. |
- F1 ⌘/ |
-
| Help > About | -See which adb port the emulator uses, as well as the Android and - emulator version numbers. Compare the latest available emulator version - with your version to determine if you have the latest software installed. - -The emulator serial number is emulator-adb_port, - which you can specify as an adb command line option, for example. |
- F1 ⌘/ |
-
An Android Virtual Device (AVD) is an emulator configuration that lets you model an actual - device by defining hardware and software options to be emulated by the Android Emulator.
- -The easiest way to create an AVD is to use the graphical
- AVD Manager, which you launch
- from Android Studio by clicking Tools > Android > AVD Manager. You can
- also start the AVD Manager from the command line by calling the android tool with
- the avd options, from the <sdk>/tools/ directory.
You can also create AVDs on the command line by passing the android tool options.
- For more information on how to create AVDs in this manner, see
- Managing Virtual Devices from the
- Command Line.
An AVD consists of:
- -You can create as many AVDs as you need, based on the types of device you want to model. - To thoroughly test your application, you should create an AVD for each general device configuration - (for example, different screen sizes and platform versions) with which your application is compatible - and test your application on each one.
- -Keep these points in mind when you are selecting a system image target for your AVD:
- -
- in Google Maps and then send a location, the map shows it.minSdkVersion attribute of the application's manifest file. For more
- information about the relationship between system API Level and application
- minSdkVersion, see Specifying Minimum System API Version.uses-library
- element in its manifest file, the application can only run on a system image in which that external
- library is present. If you want to run your application on an emulator, create an AVD that
- includes the required library. Usually, you must create such an AVD using an Add-on component for the
- AVD's platform (for example, the Google APIs Add-on contains the Google Maps library).To learn how to manage AVDs using a graphical tool, read Managing AVDs with AVD Manager. To - learn how to manage AVDs on the command line, read - Managing AVDs - from the Command Line.
- - - - - - diff --git a/docs/html/tools/devices/managing-avds-cmdline.jd b/docs/html/tools/devices/managing-avds-cmdline.jd deleted file mode 100644 index c16b1f85e6a25cb0f0efd8dfd4ffb1f5b59766ac..0000000000000000000000000000000000000000 --- a/docs/html/tools/devices/managing-avds-cmdline.jd +++ /dev/null @@ -1,369 +0,0 @@ -page.title=Managing AVDs from the Command Line -parent.title=Managing Virtual Devices -parent.link=index.html -@jd:body - -The android tool lets you manage AVDs on the command line. For a complete reference
-of the command line options that you can use, see the reference for the
-android tool.
To generate a list of system image targets, use this command:
- -android list targets- -
The android tool scans the <sdk>/platforms/ and
-<sdk>/add-ons/ directories looking for valid system images and
-then generates the list of targets. Here's an example of the command output:
-
Available Android targets: -id: 1 or "android-3" - Name: Android 1.5 - Type: Platform - API level: 3 - Revision: 4 - Skins: QVGA-L, HVGA-L, HVGA (default), HVGA-P, QVGA-P -id: 2 or "android-4" - Name: Android 1.6 - Type: Platform - API level: 4 - Revision: 3 - Skins: QVGA, HVGA (default), WVGA800, WVGA854 -id: 3 or "android-7" - Name: Android 2.1-update1 - Type: Platform - API level: 7 - Revision: 2 - Skins: QVGA, WQVGA400, HVGA (default), WVGA854, WQVGA432, WVGA800 -id: 4 or "android-8" - Name: Android 2.2 - Type: Platform - API level: 8 - Revision: 2 - Skins: WQVGA400, QVGA, WVGA854, HVGA (default), WVGA800, WQVGA432 -id: 5 or "android-9" - Name: Android 2.3 - Type: Platform - API level: 9 - Revision: 1 - Skins: HVGA (default), WVGA800, WQVGA432, QVGA, WVGA854, WQVGA400 -- - - -
In addition to creating AVDs with the
-AVD Manager user interface,
-you can also create them by passing in command line arguments to the android tool.
-
Open a terminal window and change to
-the <sdk>/tools/ directory, if needed.
To create each AVD, you issue the command android create avd,
-with options that specify a name for the new AVD and the system image you want
-to run on the emulator when the AVD is invoked. You can specify other options on
-the command line also, such as the emulated SD card size, the emulator skin, or a custom
-location for the user data files.
Here's the command-line usage for creating an AVD:
- -android create avd -n <name> -t <targetID> [-<option> <value>] ...- -
You can use any name you want for the AVD, but since you are likely to be
-creating multiple AVDs, you should choose a name that lets you recognize the
-general characteristics offered by the AVD. The target ID is an integer assigned by the
-android tool. The target ID is not derived from the system image name,
-version, or API Level, or other attribute, so you need to run the android list targets
-command to list the target ID of each system image. You should do this before you run
-the android create avd command. See the android
-tool documentation for more information on the command line options.
When you've selected the target you want to use and made a note of its ID,
-use the android create avd command to create the AVD, supplying the
-target ID as the -t argument. Here's an example that creates an
-AVD with name "my_android1.5" and target ID "2" (the standard Android 1.5
-system image in the list above):
android create avd -n my_android1.5 -t 2- -
If the target you selected was a standard Android system image ("Type:
-platform"), the android tool next asks you whether you want to
-create a custom hardware profile.
Android 1.5 is a basic Android platform. -Do you wish to create a custom hardware profile [no]- -
If you want to set custom hardware emulation options for the AVD, enter
-"yes" and set values as needed. If you want to use the default hardware
-emulation options for the AVD, just press the return key (the default is "no").
-The android tool creates the AVD with name and system image mapping you
-requested, with the options you specified. For more information, see
-Setting Hardware Emulation Options.
-
-
Note: If you are creating an AVD whose target is an SDK add-on, the
-android tool does not allow you to set hardware emulation options.
-It assumes that the provider of the add-on has set emulation options
-appropriately for the device that the add-on is modeling, and so prevents you
-from resetting the options.
When testing your application, we recommend that you test your application in several different -AVDs, using different screen configurations (different combinations of size and density). In -addition, you should set up the AVDs to run at a physical size that closely matches an actual -device.
- -To set up your AVDs for a specific resolution or density, follow these steps:
- -create avd command to create a new AVD, specifying
-the --skin option with a value that references either a default
-skin name (such as "WVGA800") or a custom skin resolution (such as 240x432).
-Here's an example:
- android create avd -n <name> -t <targetID> --skin WVGA800-
In the example above (WVGA medium density), the new AVD will emulate a 5.8" -WVGA screen.
- -As an alternative to adjusting the emulator skin configuration, you can use
-the emulator skin's default density and add the -dpi-device option
-to the emulator command line when
-starting the AVD. For example:
emulator -avd WVGA800 -scale 96dpi -dpi-device 160- - - -
When you create an AVD, the android tool creates a dedicated directory for it
-on your development computer. The directory contains the AVD configuration file,
-the user data image and SD card image (if available), and any other files
-associated with the device. Note that the directory does not contain a system
-image — instead, the AVD configuration file contains a mapping to the
-system image, which it loads when the AVD is launched.
The android tool also creates an <AVD_name>.ini file for the AVD at the
-root of the .android/avd/ directory on your computer. The file specifies the
-location of the AVD directory and always remains at the root the .android
-directory.
By default, the android tool creates the AVD directory inside
-~/.android/avd/ (on Linux/Mac), C:\Documents and
-Settings\<user>\.android\ on Windows XP, and
-C:\Users\<user>\.android\ on Windows 7 and Vista.
-If you want to use a custom location for the AVD directory, you
-can do so by using the -p <path> option when
-you create the AVD:
android create avd -n my_android1.5 -t 2 -p path/to/my/avd- -
If the .android directory is hosted on a network drive, we recommend using
-the -p option to place the AVD directory in another location.
-The AVD's .ini file remains in the .android directory on the network
-drive, regardless of the location of the AVD directory.
-
-
-
When you are creating a new AVD that uses a standard Android system image ("Type:
-platform"), the android tool lets you set hardware emulation
-options for virtual device. The table below lists the options available and the
-default values, as well as the names of properties that store the emulated
-hardware options in the AVD's configuration file (the config.ini file in the
-AVD's local directory).
Table 1. Available hardware profile options for AVDs and -the default values
- -| Characteristic | -Description | -Property | -
|---|---|---|
| Device ram size | -The amount of physical RAM on the device, in megabytes. Default value is "96". - | hw.ramSize | -
| Touch-screen support | -Whether there is a touch screen or not on the device. Default value is "yes". | -hw.touchScreen - - |
| Trackball support | -Whether there is a trackball on the device. Default value is "yes". | -hw.trackBall | -
| Keyboard support | -Whether the device has a QWERTY keyboard. Default value is "yes". | -hw.keyboard | -
| DPad support | -Whether the device has DPad keys. Default value is "yes". | -hw.dPad | -
| GSM modem support | -Whether there is a GSM modem in the device. Default value is "yes". | -hw.gsmModem | -
| Camera support | -Whether the device has a camera. Default value is "no". | -hw.camera | -
| Maximum horizontal camera pixels | -Default value is "640". | -hw.camera.maxHorizontalPixels | -
| Maximum vertical camera pixels | -Default value is "480". | -hw.camera.maxVerticalPixels | -
| GPS support | -Whether there is a GPS in the device. Default value is "yes". | -hw.gps | -
| Battery support | -Whether the device can run on a battery. Default value is "yes". | -hw.battery | -
| Accelerometer | -Whether there is an accelerometer in the device. Default value is "yes". | -hw.accelerometer | -
| Audio recording support | -Whether the device can record audio. Default value is "yes". | -hw.audioInput | -
| Audio playback support | -Whether the device can play audio. Default value is "yes". | -hw.audioOutput | -
| SD Card support | -Whether the device supports insertion/removal of virtual SD Cards. Default value is "yes". | -hw.sdCard | -
| Cache partition support | -Whether we use a /cache partition on the device. Default value is "yes". | -disk.cachePartition | -
| Cache partition size | -Default value is "66MB". | -disk.cachePartition.size | -
| Abstracted LCD density | -Sets the generalized density characteristic used by the AVD's screen. Default value is "160". | -hw.lcd.density | -
| Trackball support | -Whether there is a trackball present. | -hw.trackBall | -
If you want to move or rename an AVD, you can do so using this command:
- -android move avd -n <name> [-<option> <value>] ...- -
If, for any reason, the platform/add-on root folder has its name changed (maybe because the user has installed an update of the platform/add-on) then the AVD will not be able to load the system image that it is mapped to. In this case, the android list targets command will produce this output:
-
-
The following Android Virtual Devices could not be loaded: -Name: foo -Path: <path>/.android/avd/foo.avd -Error: Invalid value in image.sysdir. Run 'android update avd -n foo'- -
To fix this error, use the android update avd command to recompute the path to the system images.
You can use the android tool to delete an AVD. Here is the command usage:
android delete avd -n <name>- -
When you issue the command, the android tool looks for an AVD matching the
-specified name deletes the AVD's directory and files.
An Android Virtual Device (AVD) definition lets you define the - characteristics of an Android phone, tablet, Android Wear, or Android TV - device that you want to simulate in the - Android Emulator. - The AVD Manager helps you easily create and manage AVDs.
- -To effectively test your app, you should create an AVD that models each - device type that your app is designed to support. For example, we recommend - that you create an AVD for each API level that's equal to and higher than the - minimum version you've specified in your manifest - {@code <uses-sdk>} tag.
- -An AVD contains a hardware profile, system image, skin, and other - properties.
- -The hardware profile defines the characteristics of a device as - shipped from the factory. The AVD Manager comes preloaded with certain - hardware profiles, such as Nexus phone devices, and you can define and import - hardware profiles as needed. You can override some of the settings in your - AVD, if needed.
- -The AVD Manager helps you choose a system image for your AVD by providing - recommendations. It also lets - you download system images, some with add-on libraries, like Google APIs, - which your app might require. x86 system images run the fastest in the - emulator. Android Wear and Android TV devices tend to run best (and have - the largest installed base) on recent releases, while users of Android phones - and tablets tend to use slightly older releases, as shown in the - API level - dashboards.
- -An emulator skin specifies the appearance of a device. The AVD Manager - provides some predefined skins. You can also define your own, or use skins - provided by third parties.
- -Just as with a real device, for apps to use certains features defined in an
- AVD, such as the camera, it must have the corresponding
- <uses-feature>
- setting in the app manifest.
The AVD Manager lets you manage your AVDs all in one place.
- -To run the AVD Manager:
- -
- in the toolbar.The AVD Manager appears.
- -
-
-It displays any AVDs you’ve already defined. When you first install -Android Studio, it creates one AVD. If you defined AVDs for Android Emulator -24.0.x or lower, you need to recreate them.
- -From this page you can:
- -.ini and
- .img files on disk.You can create a new AVD from the beginning, or - duplicate an AVD and change some properties.
- -To create a new AVD:
- -Alternatively, - run your - app from within Android Studio. In the Select Deployment Target - dialog, click Create New Emulator.
- -The Select Hardware page appears.
-
-
- If you don't see the hardware profile you want, you can - create - or import a hardware profile.
- -The System Image page appears.
-
-
-
- The Recommended tab lists recommended system images. The - other tabs include a more complete list. The right pane describes the - selected system image. x86 images run the fastest in the emulator.
-If you see Download next to the system image, you need - to click it to download the system image. You must be connected to the - internet to download it.
- -The Verify Configuration page appears.
-
-
- Click Show Advanced Settings to show more - settings, such as the skin.
-The new AVD appears in the Your Virtual Devices page or the - Select Deployment Target dialog.
-To create an AVD starting with a copy:
- -Or click Menu
- 
- and select Duplicate.
The Verify Configuration - page appears.
- -The AVD appears in the Your Virtual Devices page. - -
The AVD Manager provides predefined hardware profiles for common devices so -you can easily add them to your AVD definitions. If -you need to define a different device, you can create a new hardware profile. -You can define a new hardware profile from the beginning, -or copy a hardware profile as a start. The preloaded -hardware profiles aren't editable.
- -To create a new hardware profile from the beginning:
-Your new hardware profile appears in the Select Hardware page. - You can optionally create an AVD - that uses the hardware profile - by clicking Next. Or, click Cancel to return - to the Your Virtual Devices page or Select Deployment Target - dialog.
-To create a hardware profile starting with a copy:
- -Or right-click a hardware profile and select Clone. - -
Your new hardware profile appears in the Select Hardware page. - You can optionally create an AVD - that uses the hardware profile - by clicking Next. Or, click Cancel to return - to the Your Virtual Devices page or Select Deployment Target - dialog.
-From the Your Virtual Devices page, you can - perform the following operations on an existing AVD:
-
and
- make your changes.
- and select Delete..ini and
- .img files on disk, right-click an AVD and select
- Show on Disk. Or click Menu
-
- and select Show on Disk.
- and select View Details.From the Select Hardware page, -you can - perform the following operations on an existing hardware profile:
-You can't edit or delete the predefined hardware profiles.
- -From the Your Virtual Devices page, you can - perform the following operations on an emulator:
-
.
- and select Stop.
- and select Wipe Data.From the Select Hardware page, -you can import and export hardware profiles:
-You can specify the following properties of hardware profiles in the -Configure Hardware Profile page. AVD -configuration properties override hardware profile properties, and emulator -properties that you set while the emulator is running override them both.
- -The predefined hardware profiles included with the AVD Manager aren't -editable. However, you can copy them and edit the copies.
- - -| Hardware Profile Property | -Description | -
|---|---|
| Device Name | -Name of the hardware profile. The name can contain uppercase or - lowercase letters, - numbers from 0 to 9, periods (.), underscores (_), and parentheses ( () ). - The name of the file storing the hardware profile is derived from the - hardware profile name. - | -
| Device Type | -Select one of the following:
-
|
-
| Screen Size | -The physical size of the screen, in inches, measured at the diagonal. - If the size is larger than your computer screen, it’s reduced in size at - launch. | -
| Screen Resolution | -Type a width and height in pixels to specify the total number of pixels - on the simulated screen. | - -
| Round | -Select this option if the device has a round screen, such as an - Android Wear device. | -
| Memory: RAM | -Type a RAM size for the device and select the units, one of B (byte), - KB (kilobyte), MB (megabyte), GB (gigabyte), or TB (terabyte). | -
| Input: Has Hardware Buttons (Back/Home/Menu) | -Select this option if your device has hardware navigation buttons. - Deselect it if these buttons are implemented in software only. If you - select this option, the buttons won’t appear on the screen. You can use the - emulator side panel to “press” the buttons, in either case. | -
| Input: Has Hardware Keyboard | -Select this option if your device has a hardware keyboard. Deselect it - if it doesn’t. If you select this option, a keyboard won’t appear on the - screen. You can use your computer keyboard to send keystrokes to the - emulator, in either case. | -
| Navigation Style | -Select one of the following: -
These options are for actual hardware controls on the device itself. - However, - the events sent to the device by an external controller are the same. - |
-
| Supported Device States | -Select one or both options: -
If you select both, you can switch between orientations in the emulator. -You must select at least one option to continue. |
-
| Cameras | -Select one or both options: -
Later, you can use a webcam or a photo provided by the emulator to simulate -taking a photo with the camera. |
-
| Sensors: Accelerometer | -Select if the device has hardware that helps the device determine - its orientation. | -
| Sensors: Gyroscope | -Select if the device has hardware that detects rotation or twist. - In combination with an - accelerometer, it can provide smoother orientation detection and support - a six-axis orientation system. | -
| Sensors: GPS | -Select if the device has hardware that supports the Global Positioning - System (GPS) - satellite-based navigation system. | -
| Sensors: Proximity Sensor | -Select if the device has hardware that detects if the device is close - to your face during a - phone call to disable input from the screen. | -
| Default Skin | -Select a skin that controls what the device looks like when displayed - in the - emulator. Remember that specifying a screen size that's too small for the - resolution can mean that the screen is cut off, so you can't see the whole - screen. See - Creating Emulator Skins - for more information. | -
You can specify the following properties for AVD configurations -in the Verify Configuration page. -The AVD configuration specifies the interaction between the development -computer and the emulator, as well as properties you want to override in the -hardware profile.
- -AVD configuration properties override hardware profile properties, -and emulator -properties that you set while the emulator is running override them both.
- -| AVD Property | -Description | -
|---|---|
| AVD Name | -Name of the AVD. The name can contain uppercase or - lowercase letters, - numbers from 0 to 9, periods (.), underscores (_), and parentheses ( () ). - The name of the file storing the AVD configuration is derived from the AVD - name. - | -
| AVD ID (Advanced) | -The AVD filename is derived from the ID, and you can use the ID to - refer to the AVD from the command line. | -
| Hardware Profile | -Click Change to select a different hardware profile in - the Select Hardware page. | -
| System Image | -Click Change to select a different system image in the - System Image page. - An active internet connection is required to download a new image. | -
| Startup: Scale | -Select the initial size you want to use when the emulator launches. - This size might be adjusted to a smaller size if it’s larger than the - computer screen. The default is Auto (automatic). | -
| Startup: Orientation | -Select one option for the initial emulator orientation: -
An option is enabled only if it’s selected in the hardware profile. When -running the AVD in the emulator, you can change the orientation if portrait and -landscape are supported in the hardware profile. |
-
| Camera (Advanced) | -Select one or both options: -
This option is available only if it's selected in the hardware profile; it's -not available for Android Wear and Android TV. |
-
| Network: Speed (Advanced) | -Select a network protocol to determine the speed of data transfer: - -
|
-
| Network: Latency (Advanced) | -Select a network protocol to set how much time (delay) it takes for the - protocol to transfer a data packet from one point to another point. | -
| Emulated Performance: Graphics | -Select how graphics are rendered in the emulator: -
|
-
| Multi-Core CPU (Advanced) | -Select the number of processor cores on your computer that you’d like - to use for the emulator. Using more processor cores speeds up the emulator. - | -
| Memory and Storage: RAM | -The amount of RAM on the device. This value is set by the hardware - manufacturer, but you can override it, if needed, such as for faster - emulator operation. Increasing the size uses more resources on your - computer. Type a RAM size and select the - units, one of B (byte), KB (kilobyte), MB (megabyte), GB (gigabyte), or - TB (terabyte). | -
| Memory and Storage: VM Heap | -The VM heap size. This value is set by the hardware - manufacturer, but you can override it, if needed. Type a heap size and - select the - units, one of B (byte), KB (kilobyte), MB (megabyte), GB (gigabyte), or - TB (terabyte). For more information on Android VMs, see - Memory Management for - Different Virtual Machines. | -
| Memory and Storage: Internal Storage | -The amount of nonremovable memory space available on the device. This - value is set by the hardware - manufacturer, but you can override it, if needed. Type a size and select the - units, one of B (byte), KB (kilobyte), MB (megabyte), GB (gigabyte), or - TB (terabyte). | -
| Memory and Storage: SD Card | -The amount of removable memory space available to store data on the - device. To use a virtual SD card managed by Android Studio, select - Studio, type a size, and select the - units, one of B (byte), KB (kilobyte), MB (megabyte), GB (gigabyte), or - TB (terabyte). A minimum of 100 MB is recommended to use the camera. To - manage the space in a file, select External File and - click ... to specify the file and location. For more - information, see mksdcard. - | -
| Device Frame: Enable Device Frame | -Select to enable a frame around the emulator window that mimics the - look of a real device. | -
| Custom Skin Definition (Advanced) | -Select a skin that controls what the device looks like when displayed in - the emulator. Remember that specifying a screen size that's too small for - the resolution can mean that the screen is cut off, so you can't see the - whole screen. See - Creating Emulator Skins - for more information. | -
| Keyboard: Enable Keyboard Input (Advanced) | -Select this option if you want to use your hardware keyboard to interact - with the emulator. It's disabled for Android Wear and Android TV. | -
An Android emulator skin is a collection of files that define the visual -and control elements of -an emulator display. If the skin definitions available in the AVD settings -don't meet your requirements, -you can create your own custom skin definition, and then apply it to your AVD. -
- -Each emulator skin contains:
-hardware.ini fileTo create and use a custom skin:
-layout. This file defines many characteristics of the skin,
- such as the
- size and image assets for specific buttons. For example:
-
-parts {
- device {
- display {
- width 320
- height 480
- x 0
- y 0
- }
- }
-
- portrait {
- background {
- image background_port.png
- }
-
- buttons {
- power {
- image button_vertical.png
- x 1229
- y 616
- }
- }
- }
- ...
-}
-hardware.ini
- file for the device settings, such as hw.keyboard and
- hw.lcd.density.For more detailed information about creating emulator skins, see the -Android Emulator Skin File Specification in the tools source code.
- - - diff --git a/docs/html/tools/extras/index.jd b/docs/html/tools/extras/index.jd deleted file mode 100644 index 8da26dcdab12ed450fdcca48a633dd29e76c7500..0000000000000000000000000000000000000000 --- a/docs/html/tools/extras/index.jd +++ /dev/null @@ -1,5 +0,0 @@ -page.title=Extras -page.noplus=1 -@jd:body - -SDK extras add functionality to your development environment. You can download all of the SDK extras into your development environment using the SDK Manager.
diff --git a/docs/html/tools/extras/oem-usb.jd b/docs/html/tools/extras/oem-usb.jd deleted file mode 100644 index cf15048135dae78a6562d33d881071623ea18f1c..0000000000000000000000000000000000000000 --- a/docs/html/tools/extras/oem-usb.jd +++ /dev/null @@ -1,405 +0,0 @@ -page.title=OEM USB Drivers -@jd:body - -If you are developing on Windows and would like to connect an Android-powered device -to test your applications, then you need to install the appropriate USB driver. This document -provides links to the web sites for several original equipment manufacturers (OEMs), -where you can download the appropriate USB driver for your device. However, this list is -not exhaustive for all available Android-powered devices.
- -If you're developing on Mac OS X or Linux, then you probably don't need to install a USB driver. -To start developing with your device, read Using Hardware Devices.
- -The Google USB Driver is required for Windows only in order to perform -adb debugging with any of -the Google Nexus devices. The one exception is the -Galaxy Nexus: the driver for Galaxy Nexus is distributed by Samsung -(listed as model GT-I9250TSGGEN).
- - - -First, find the appropriate driver for your device from the OEM drivers -table below.
- -Once you've downloaded your USB driver, follow the instructions below to install or upgrade the -driver, based on your version of Windows and whether you're installing for the first time -or upgrading an existing driver.
- -Tip: When you finish the USB driver installation, -see Using Hardware Devices for -other important information about using an Android-powered device for -development.
- -Caution:
-You may make changes to android_winusb.inf file found inside
-usb_driver\ (for example, to add support for other devices),
-however, this will lead to security warnings when you install or upgrade the
-driver. Making any other changes to the driver files may break the installation
-process.
To install the Android USB driver on Windows 7 for the first time:
-Or, to upgrade an existing Android USB driver on Windows 7 with the new -driver:
- -To install the Android USB driver on Windows Vista for the first time:
- -Or, to upgrade an existing Android USB driver on Windows Vista with the new -driver:
- -
- A monkeyrunner class that represents a device or emulator accessible by the workstation running
-monkeyrunner.
-
- This class is used to control an Android device or emulator. The methods send UI events, - retrieve information, install and remove applications, and run applications. -
-
- You normally do not have to create an instance of MonkeyDevice. Instead, you
- use
-
-MonkeyRunner.waitForConnection() to create a new object from a connection to a device or
-emulator. For example, instead of
-using:
-newdevice = MonkeyDevice() --
- you would use: -
--newdevice = MonkeyRunner.waitForConnection() --
| Constants | -|||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
| string | -DOWN | -
- Use this with the type argument of
- press() or touch()
-
- to send a DOWN event.
- |
- |||||||||
| string | -UP | -
- Use this with the type argument of
- press() or touch()
-
- to send an UP event.
- |
- |||||||||
| string | -DOWN_AND_UP | -
- Use this with the type argument of
- press() or touch()
-
- to send a DOWN event immediately followed by an UP event.
- |
- |||||||||
| Methods | -|||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
|
- |
-
-
- Broadcasts an Intent to this device, as if the Intent were coming from an
- application.
-
- |
- ||||||||||
|
- |
-
-
- Simulates a drag gesture (touch, hold, and move) on this device's screen.
-
- |
- ||||||||||
|
- |
-
-
- Given the name of a system environment variable, returns its value for this device.
- The available variable names are listed in the
- detailed description of this method.
-
- |
- ||||||||||
|
- |
-
-
-. The API equivalent of
- adb shell getprop <key>. This is provided for use
- by platform developers.
- |
- ||||||||||
|
- |
-
-
- Installs the Android application or test package contained in packageFile onto this
- device. If the application or test package is already installed, it is replaced.
-
- |
- ||||||||||
|
- |
-
-
- Runs the specified component under Android instrumentation, and returns the results
- in a dictionary whose exact format is dictated by the component being run. The
- component must already be present on this device.
-
- |
- ||||||||||
|
- |
-
-
- Sends the key event specified by type to the key specified by
- keycode.
-
- |
- ||||||||||
|
- |
-
-
- Reboots this device into the bootloader specified by bootloadType.
-
- |
- ||||||||||
|
- |
-
-
- Deletes the specified package from this device, including its data and cache.
-
- |
- ||||||||||
|
- |
-
-
- Executes an
- adb shell command and returns the result, if any.
- |
- ||||||||||
|
- |
-
-
- Starts an Activity on this device by sending an Intent constructed from the
- supplied arguments.
-
- |
- ||||||||||
-
-
- MonkeyImage
-
-
- |
-
-
- Captures the entire screen buffer of this device, yielding a
-
-
-
- MonkeyImage
-
- object containing a screen capture of the current display.
- |
- ||||||||||
|
- |
-
-
- Sends a touch event specified by type to the screen location specified
- by x and y.
-
- |
- ||||||||||
|
- |
-
-
- Sends the characters contained in message to this device, as if they
- had been typed on the device's keyboard. This is equivalent to calling
-
- press() for each keycode in message
- using the key event type DOWN_AND_UP.
- |
- ||||||||||
|
- |
-
-
- Wakes the screen of this device.
-
- |
- ||||||||||
- Broadcasts an Intent to this device, as if the Intent were coming from an - application. See {@link android.content.Intent Intent} for more information about the - arguments. -
-| uri | -- The URI for the Intent. - (see {@link android.content.Intent#setData(android.net.Uri) Intent.setData()}). - | -
|---|---|
| action | -- The action for this Intent - (see {@link android.content.Intent#setAction(java.lang.String) Intent.setAction()}). - | -
| data | -- The data URI for this Intent - (see {@link android.content.Intent#setData(android.net.Uri) Intent.setData()}). - | -
| mimetype | -- The MIME type for the Intent - (see {@link android.content.Intent#setType(java.lang.String) Intent.setType()}). - | -
| categories | -- An iterable data structure containing strings that define categories for this - Intent - (see - {@link android.content.Intent#addCategory(java.lang.String) Intent.addCategory()}). - | -
| extras | -
- A dictionary of extra data for this Intent
- (see {@link android.content.Intent#putExtra(java.lang.String,java.lang.String)
- Intent.putExtra()}
- for an example).
- - The key for each dictionary item should be a string. The item's value - can be any simple or structured data type. - - |
-
| component | -- The component for this Intent (see {@link android.content.ComponentName}). - Using this argument will direct the Intent to a specific class within a specific - Android package. - | -
| flags | -- An iterable data structure containing flags that control how the Intent is handled - (see {@link android.content.Intent#setFlags(int) Intent.setFlags()}). - | -
- Simulates a drag gesture (touch, hold, and move) on this device's screen. -
-| start | -- The starting point of the drag gesture, in the form of a tuple - (x,y) where x and y are integers. - | -
|---|---|
| end | -- The end point of the drag gesture, in the form of a tuple (x,y) - where x and y are integers. - | -
| duration | -The duration of the drag gesture in seconds. The default is 1.0 seconds. | -
| steps | -The number of steps to take when interpolating points. The default is 10. | -
- Given the name of a system environment variable, returns its value for this device. -
-| key | -- The name of the system environment variable. The available variable names are listed in - Table 1. Property variable names at the end of this topic. - | -
|---|
- Synonym for getProperty().
-
| key | -- The name of the system environment variable. The available variable names are listed in - Table 1. Property Variable Names. - | -
|---|
- Installs the Android application or test package contained in packageFile - onto this device. If the application or test package is already installed, it is - replaced. -
-| path | -
- The fully-qualified path and filename of the .apk file to install.
- |
-
|---|
- Runs the specified component with Android instrumentation, and returns the results - in a dictionary whose exact format is dictated by the component being run. The - component must already be present on this device. -
-- Use this method to start a test case that uses one of Android's test case classes. - See Testing - Fundamentals to learn more about unit testing with the Android testing - framework. -
-| className | -
- The name of an Android component that is already installed on this device, in the
- standard form packagename/classname, where packagename is the
- Android package name of a .apk file on this device, and
- classname is the class name of an Android component (Activity,
- ContentProvider, Service, or BroadcastReceiver) in that file. Both
- packagename and classname must be fully qualified. See
- {@link android.content.ComponentName} for more details.
- |
-
|---|---|
| args | -- A dictionary containing flags and their values. These are passed to the component as it - is started. If the flag does not take a value, set its dictionary value to an empty - string. - | -
- A dictionary containing the component's output. The contents of the dictionary - are defined by the component itself. -
-
- If you use {@link android.test.InstrumentationTestRunner} as the class name in
- the componentName argument, then the result dictionary contains
- the single key "stream". The value of "stream" is a string containing
- the test output, as if InstrumentationTestRunner was run from the
- command line. The format of this output is described in
-
- Testing in Other IDEs.
-
- Sends the key event specified by type to the key specified by
- keycode.
-
| name | -- The name of the keycode to send. See {@link android.view.KeyEvent} for a list of - keycode names. Use the keycode name, not its integer value. - | -
|---|---|
| type | -
- The type of key event to send. The allowed values are
- DOWN, UP, and
- DOWN_AND_UP.
- |
-
- Reboots this device into the bootloader specified by bootloadType.
-
| into | -- The type of bootloader to reboot into. The allowed values are - "bootloader", "recovery", or "None". - | -
|---|
- Deletes the specified package from this device, including its data and cache. -
-| package | -
- The Android package name of an .apk file on this device.
- |
-
|---|
- Executes an adb shell command and returns the result, if any.
-
| cmd | -
- The command to execute in the adb shell. The form of these commands is
- described in the topic Android
- Debug Bridge.
- |
-
|---|
- Starts an Activity on this device by sending an Intent constructed from the - supplied arguments. -
-| uri | -- The URI for the Intent. - (see {@link android.content.Intent#setData(android.net.Uri) Intent.setData()}). - | -
|---|---|
| action | -- The action for the Intent - (see {@link android.content.Intent#setAction(java.lang.String) Intent.setAction()}). - | -
| data | -- The data URI for the Intent - (see {@link android.content.Intent#setData(android.net.Uri) Intent.setData()}). - | -
| mimetype | -- The MIME type for the Intent - (see {@link android.content.Intent#setType(java.lang.String) Intent.setType()}). - | -
| categories | -- An iterable data structure containing strings that define categories for the - Intent - (see - {@link android.content.Intent#addCategory(java.lang.String) Intent.addCategory()}). - | -
| extras | -
- A dictionary of extra data for the Intent
- (see
- {@link android.content.Intent#putExtra(java.lang.String,java.lang.String)
- Intent.putExtra()}
- for an example).
- - The key for each dictionary item should be a string. The item's value - can be any simple or structured data type. - - |
-
| component | -- The component for the Intent - (see {@link android.content.ComponentName}). Using this argument will direct the - Intent to a specific class within a specific Android package. - | -
| flags | -- An iterable data structure containing flags that control how the Intent is handled - (see {@link android.content.Intent#setFlags(int) Intent.setFlags()}). - | -
-
- MonkeyImage
-
-
-
- takeSnapshot
-
- ()
-
- - Captures the entire screen buffer of this device, yielding a - screen capture of the current display. -
-- Sends a touch event specified by type to the screen location specified - by x and y. -
-| x | -- The horizontal position of the touch in actual device pixels, starting from the left of - the screen in its current orientation. - | -
|---|---|
| y | -- The vertical position of the touch in actual device pixels, starting from the top of - the screen in its current orientation. - | -
| type | -
- The type of key event to send. The allowed values are
- DOWN, UP, and
- DOWN_AND_UP.
- |
-
- Sends the characters contained in message to this device, as if they
- had been typed on the device's keyboard. This is equivalent to calling
- press() for each keycode in message
- using the key event type DOWN_AND_UP.
-
| message | -- A string containing the characters to send. - | -
|---|
- Wakes the screen of this device. -
-- Table 1.Property variable names used with - getProperty() and - getSystemProperty(). -
-| - Property Group - | -- Property - | -- Description - | -- Notes - | -
|---|---|---|---|
build |
- board |
- Code name for the device's system board | -- See {@link android.os.Build} - | -
brand |
- The carrier or provider for which the OS is customized. | -||
device |
- The device design name. | -||
fingerprint |
- A unique identifier for the currently-running build. | -||
host |
- - | ||
ID |
- A changelist number or label. | -||
model |
- The end-user-visible name for the device. | -||
product |
- The overall product name. | -||
tags |
- Comma-separated tags that describe the build, such as "unsigned" and "debug". | -||
type |
- The build type, such as "user" or "eng". | -||
user |
- - | ||
CPU_ABI |
- - The name of the native code instruction set, in the form CPU type plus - ABI convention. - | -||
manufacturer |
- The product/hardware manufacturer. | -||
version.incremental |
- - The internal code used by the source control system to represent this version - of the software. - | -||
version.release |
- The user-visible name of this version of the software. | -||
version.sdk |
- The user-visible SDK version associated with this version of the OS. | -||
version.codename |
- - The current development codename, or "REL" if this version of the software has been - released. - | -||
display |
- width |
- The device's display width in pixels. | -- See - {@link android.util.DisplayMetrics} for details. - | -
height |
- The device's display height in pixels. | -||
density |
-
- The logical density of the display. This is a factor that scales
- DIP (Density-Independent Pixel) units to the device's resolution. DIP is adjusted so
- that 1 DIP is equivalent to one pixel on a 160 pixel-per-inch display. For example,
- on a 160-dpi screen, density = 1.0, while on a 120-dpi screen, density = .75.
- - The value does not exactly follow the real screen size, but is adjusted to - conform to large changes in the display DPI. See - {@link android.util.DisplayMetrics#density} for more details. - - |
- ||
am.current |
- package |
- The Android package name of the currently running package. | -
- The am.current keys return information about the currently-running
- Activity.
- |
-
action |
-
- The current activity's action. This has the same format as the name
- attribute of the action element in a package manifest.
- |
- ||
comp.class |
-
- The class name of the component that started the current Activity. See
- comp.package for more details. |
- ||
comp.package |
- - The package name of the component that started the current Activity. A component - is specified by a package name and the name of class that the package contains. - | -||
data |
- The data (if any) contained in the Intent that started the current Activity. | -||
categories |
- The categories specified by the Intent that started the current Activity. | -||
clock |
- realtime |
- - The number of milliseconds since the device rebooted, including deep-sleep - time. - | -- See {@link android.os.SystemClock} for more information. - | -
uptime |
- - The number of milliseconds since the device rebooted, not including - deep-sleep time - | -||
millis |
- current time since the UNIX epoch, in milliseconds. | -
- A monkeyrunner class to hold an image of the device or emulator's screen. The image is
- copied from the screen buffer during a screenshot. This object's methods allow you to
- convert the image into various storage formats, write the image to a file, copy parts of
- the image, and compare this object to other MonkeyImage objects.
-
- You do not need to create new instances of MonkeyImage. Instead, use
-
-MonkeyDevice.takeSnapshot() to create a new instance from a screenshot. For example, use:
-
-newimage = MonkeyDevice.takeSnapshot() --
| Methods | -|||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
|
- |
-
-
- Converts the current image to a particular format and returns it as a
- string that you can then access as an iterable of binary bytes.
-
- |
- ||||||||||
|
- |
-
-
- Returns the single pixel at the image location (x,y), as an
- a tuple of integer, in the form (a,r,g,b).
-
- |
- ||||||||||
|
- |
-
-
- Returns the single pixel at the image location (x,y), as
- a 32-bit integer.
-
- |
- ||||||||||
-
- MonkeyImage
-
- |
-
-
- Creates a new
- MonkeyImage object from a rectangular selection of the
- current image.
- |
- ||||||||||
|
- |
-
- MonkeyImage
- other,
- float percent)
-
- Compares this
- MonkeyImage object to another and returns the result of
- the comparison. The percent argument specifies the percentage
- difference that is allowed for the two images to be "equal".
- |
- ||||||||||
|
- |
-
-
- Writes the current image to the file specified by
- filename, in the
- format specified by format.
- |
- ||||||||||
- Converts the current image to a particular format and returns it as a string - that you can then access as an iterable of binary bytes. -
-| format | -- The desired output format. All of the common raster output formats are supported. - The default value is "png" (Portable Network Graphics). - | -
|---|
- Returns the single pixel at the image location (x,y), as an - a tuple of integer, in the form (a,r,g,b). -
-| x | -- The horizontal position of the pixel, starting with 0 at the left of the screen in the - orientation it had when the screenshot was taken. - | -
|---|---|
| y | -- The vertical position of the pixel, starting with 0 at the top of the screen in the - orientation it had when the screenshot was taken. - | -
- Returns the single pixel at the image location (x,y), as an - an integer. Use this method to economize on memory. -
-| x | -- The horizontal position of the pixel, starting with 0 at the left of the screen in the - orientation it had when the screenshot was taken. - | -
|---|---|
| y | -- The vertical position of the pixel, starting with 0 at the top of the screen in the - orientation it had when the screenshot was taken. - | -
- MonkeyImage
-
-
- getSubImage
-
- (tuple rect)
-
-
- Creates a new MonkeyImage object from a rectangular selection of the
- current image.
-
| rect | -
- A tuple (x, y, w, h) specifying the selection. x and y specify the 0-based pixel
- position of the upper left-hand corner of the selection. w specifies the width of the
- region, and h specifies its height, both in units of pixels.
- - The image's orientation is the same as the screen orientation at the time the - screenshot was made. - - |
-
|---|
MonkeyImage object containing the selection.
-
- MonkeyImage
- otherImage,
- float percent
- )
-
-
- Compares this MonkeyImage object to another and returns the result of
- the comparison. The percent argument specifies the percentage
- difference that is allowed for the two images to be "equal".
-
| other | -
- Another MonkeyImage object to compare to this one.
- |
-
|---|---|
| - percent - | -
- A float in the range 0.0 to 1.0, inclusive, indicating
- the percentage of pixels that need to be the same for the method to return
- true. The default is 1.0, indicating that all the pixels
- must match.
- |
-
true if the images match, or boolean false otherwise.
-
- Writes the current image to the file specified by filename, in the
- format specified by format.
-
| path | -- The fully-qualified filename and extension of the output file. - | -
|---|---|
| - format - | -- The output format to use for the file. If no format is provided, then the - method tries to guess the format from the filename's extension. If no - extension is provided and no format is specified, then the default format of - "png" (Portable Network Graphics) is used. - | -
- A monkeyrunner class that contains static utility methods. -
-| Methods | -|||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
|
- |
-
-
- Displays an alert dialog to the process running the current
- program.
-
- |
- ||||||||||
|
- |
-
-
- Displays a dialog with a list of choices to the process running the current program.
-
- |
- ||||||||||
|
- |
-
-
- Displays the monkeyrunner API reference in a style similar to that of Python's
-
- pydoc tool, using the specified format.
- |
- ||||||||||
|
- |
-
-
- Displays a dialog that accepts input.
-
- |
- ||||||||||
|
- |
-
-
- Pauses the current program for the specified number of seconds.
-
- |
- ||||||||||
-
- MonkeyDevice
-
- |
-
-
- Tries to make a connection between the
- monkeyrunner backend and the
- specified device or emulator.
- |
- ||||||||||
- Displays an alert dialog to the process running the current - program. The dialog is modal, so the program pauses until the user clicks the dialog's - button. -
-| message | -- The message to display in the dialog. - | -
|---|---|
| title | -- The dialog's title. The default value is "Alert". - | -
| okTitle | -- The text displayed in the dialog button. The default value is "OK". - | -
- Displays a dialog with a list of choices to the process running the current program. The - dialog is modal, so the program pauses until the user clicks one of the dialog's - buttons. -
-| message | -- The prompt message displayed in the dialog. - | -
|---|---|
| choices | -- A Python iterable containing one or more objects that are displayed as strings. The - recommended form is an array of strings. - | -
| - title - | -- The dialog's title. The default is "Input". - | -
- Displays the monkeyrunner API reference in a style similar to that of Python's
- pydoc tool, using the specified format.
-
| format | -- The markup format to use in the output. The possible values are "text" for plain text - or "html" for HTML. - | -
|---|
- Displays a dialog that accepts input and returns it to the program. The dialog is - modal, so the program pauses until the user clicks one of the dialog's buttons. -
-- The dialog contains two buttons, one of which displays the okTitle value - and the other the cancelTitle value. If the user clicks the okTitle button, - the current value of the input box is returned. If the user clicks the cancelTitle - button, an empty string is returned. -
-| message | -- The prompt message displayed in the dialog. - | -
|---|---|
| initialValue | -- The initial value to display in the dialog. The default is an empty string. - | -
| title | -- The dialog's title. The default is "Input". - | -
| okTitle | -- The text displayed in the okTitle button. The default is "OK". - | -
| cancelTitle | -- The text displayed in the cancelTitle button. The default is "Cancel". - | -
- Pauses the current program for the specified number of seconds. -
-| seconds | -- The number of seconds to pause. - | -
|---|
- MonkeyDevice
-
-
- waitForConnection
-
- (float timeout,
- string deviceId)
-
-
- Tries to make a connection between the monkeyrunner backend and the
- specified device or emulator.
-
| timeout | -- The number of seconds to wait for a connection. The default is to wait forever. - | -
|---|---|
| - deviceId - | -- A regular expression that specifies the serial number of the device or emulator. See - the topic - Android Debug Bridge - for a description of device and emulator serial numbers. - | -
MonkeyDevice
- instance for the device or emulator. Use this object to control and communicate with the
- device or emulator.
- Android Debug Bridge (adb) is a versatile command line tool that lets you communicate with an -emulator instance or connected Android-powered device. It is a client-server program that includes -three components:
- -You can find the {@code adb} tool in {@code <sdk>/platform-tools/}.
- -When you start an adb client, the client first checks whether there is an adb server -process already running. If there isn't, it starts the server process. When the server starts, -it binds to local TCP port 5037 and listens for commands sent from adb clients—all adb -clients use port 5037 to communicate with the adb server.
- -The server then sets up connections to all running emulator/device instances. It locates emulator/device instances by scanning odd-numbered ports in the range 5555 to 5585, the range used by emulators/devices. Where the server finds an adb daemon, it sets up a connection to that port. Note that each emulator/device instance acquires a pair of sequential ports — an even-numbered port for console connections and an odd-numbered port for adb connections. For example:
- -
-Emulator 1, console: 5554
-Emulator 1, adb: 5555
-Emulator 2, console: 5556
-Emulator 2, adb: 5557
-and so on...
-
As shown, the emulator instance connected to adb on port 5555 is the same as the instance -whose console listens on port 5554.
- -Once the server has set up connections to all emulator instances, you can use adb commands to -access those instances. Because the server manages connections to emulator/device -instances and handles commands from multiple adb clients, you can control any emulator/device -instance from any client (or from a script).
- - -In order to use adb with a device connected over USB, you must enable -USB debugging in the device system settings, under -Developer options.
- -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.
- -On some devices, the Developer options screen may be located or named differently.
- -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.
- -For more information about connecting to a device over USB, read -Using Hardware Devices.
- - - - -You can issue adb commands from a command line on your development machine or from a script. -The usage is:
- --adb [-d|-e|-s <serialNumber>] <command> -- -
If there's only one emulator running or only one device connected, the adb command is
-sent to that device by default. If multiple emulators are running and/or multiple devices are
-attached, you need to use the -d, -e, or -s
-option to specify the target device to which the command should be directed.
The table below lists all of the supported adb commands and explains their meaning and usage.
- -Table 1. Available adb commands
-| Category | -Command | -Description | -Comments | -
|---|---|---|---|
| Target Device | --d |
-Direct an adb command to the only attached USB device. | -Returns an error if more than one USB device is attached. | -
-e |
-Direct an adb command to the only running emulator instance. | -Returns an error if more than one emulator instance is running. | -|
-s <serialNumber> |
-Direct an adb command a specific emulator/device instance, referred to by its adb-assigned serial number (such as "emulator-5556"). | -See Directing -Commands to a Specific Emulator/Device Instance. | -|
| General | -devices |
-Prints a list of all attached emulator/device instances. | -See Querying for Emulator/Device Instances for more information. | -
help |
-Prints a list of supported adb commands. | -- | |
version |
-Prints the adb version number. | -- | |
| Debug | -logcat [option] [filter-specs] |
-Prints log data to the screen. | -- |
bugreport |
-Prints dumpsys, dumpstate, and logcat data to the screen, for the purposes of bug reporting. |
-- | |
jdwp |
-Prints a list of available JDWP processes on a given device. | -You can use the forward jdwp:<pid> port-forwarding specification to connect to a specific JDWP process. For example: - adb forward tcp:8000 jdwp:472- jdb -attach localhost:8000
- |
-|
| Data | -install <path-to-apk> |
-Pushes an Android application (specified as a full path to an .apk file) to an emulator/device. | -- |
pull <remote> <local> |
-Copies a specified file from an emulator/device instance to your development computer. | -- | |
push <local> <remote> |
-Copies a specified file from your development computer to an emulator/device instance. | -- | |
| Ports and Networking | -forward <local> <remote> |
-Forwards socket connections from a specified local port to a specified remote port on the emulator/device instance. | -Port specifications can use these schemes:
-
|
-
ppp <tty> [parm]... |
-Run PPP over USB.
-
Note that you should not automatically start a PPP connection. |
-- | |
| Scripting | -get-serialno |
-Prints the adb instance serial number string. | -See Querying for Emulator/Device Instances for more information. | -
get-state |
-Prints the adb state of an emulator/device instance. | - -||
wait-for-device |
-Blocks execution until the device is online — that is, until the instance state is device. |
-You can prepend this command to other adb commands, in which case adb will wait until the emulator/device instance is connected before issuing the other commands. Here's an example:
-adb wait-for-device shell getprop- -Note that this command does not cause adb to wait until the entire system is fully booted. For that reason, you should not prepend it to other commands that require a fully booted system. As an example, the install requires the Android package manager, which is available only after the system is fully booted. A command such as
-
-adb wait-for-device install <app>.apk- -would issue the install command as soon as the emulator or device instance connected to the adb server, but before the Android system was fully booted, so it would result in an error. |
-|
| Server | -start-server |
-Checks whether the adb server process is running and starts it, if not. | -- |
kill-server |
-Terminates the adb server process. | -- | |
| Shell | -shell |
-Starts a remote shell in the target emulator/device instance. | -See ADB Shell Commands for more information. | -
shell [shellCommand] |
-Issues a shell command in the target emulator/device instance and then exits the remote shell. | -
Before issuing adb commands, it is helpful to know what emulator/device instances are connected to the adb server. You can generate a list of attached emulators/devices using the devices command:
adb devices- -
In response, adb prints this status information for each instance:
- -<type>-<consolePort>.
- Here's an example serial number: emulator-5554offline — the instance is not connected to adb or is not responding.device — the instance is now connected to the adb server. Note that this state does not
- imply that the Android system is fully booted and operational, since the instance connects to adb
- while the system is still booting. However, after boot-up, this is the normal operational state of
- an emulator/device instance.no device — there is no emulator/device connected.
- The output for each instance is formatted like this:
- -[serialNumber] [state]- -
Here's an example showing the devices command and its output:
adb devices -List of devices attached -emulator-5554 device -emulator-5556 device -emulator-5558 device- - - - - - -
If multiple emulator/device instances are running, you must specify a target instance
-when issuing adb commands. To do so, use the -s option in the commands. The usage
-for the -s option is:
adb -s <serialNumber> <command>- -
As shown, you specify the target instance for a command using its adb-assigned serial number.
-You can use the devices command to obtain the serial numbers of running
-emulator/device instances. For example:
adb -s emulator-5556 install helloWorld.apk- -
Note that, if you issue a command without specifying a target emulator/device instance -while multiple devices are available, adb generates an error. - -
If you have multiple devices available (hardware or emulated), but only one is an emulator, -simply use the {@code -e} option to send commands to the emulator. Likewise if there's multiple -devices but only one hardware device attached, use the {@code -d} option to send commands to -the hardware device. - - - - -
You can use adb to copy an application from your development computer and install it on an emulator/device instance. To do so, use the install command. With the command, you must specify the path to the .apk file that you want to install:
adb install <path_to_apk>- -
For more information about how to create an .apk file that you can install on an emulator/device -instance, see Building and Running
- -Note that, if you are using Android Studio, you do not need to use adb (or aapt) directly to install your application on the emulator/device. Instead, Android Studio handles the packaging and installation of the application for you.
- - - - - - -You can use the forward command to set up arbitrary port forwarding — forwarding of requests on a specific host port to a different port on an emulator/device instance. Here's how you would set up forwarding of host port 6100 to emulator/device port 7100:
adb forward tcp:6100 tcp:7100-
You can also use adb to set up forwarding to named abstract UNIX domain sockets, as illustrated here:
-adb forward tcp:6100 local:logd- - - - - -
You can use the adb commands pull and push to copy files to
-and from an emulator/device instance. Unlike the install command,
-which only copies an APK file to a specific location, the pull and push
-commands let you copy arbitrary directories and files to any location in an
-emulator/device instance.
To copy a file or directory (and its sub-directories) from the emulator or device, use
-adb pull <remote> <local>- -
To copy a file or directory (and its sub-directories) to the emulator or device, use
-adb push <local> <remote>- -
In the commands, <local> and <remote> refer to the
-paths to the target files/directory on your development machine (local) and on the
-emulator/device instance (remote). For example:
adb push foo.txt /sdcard/foo.txt- - - - -
In some cases, you might need to terminate the adb server process and then restart it -to resolve the problem (e.g., if adb does not respond to a command).
- -To stop the adb server, use the kill-server command.
-You can then restart the server by issuing any other adb command.
-adb is usually used over USB. However, it is also possible to use over -Wi-Fi, as described here. -
- -Connect your Android device and adb host computer -to a common Wi-Fi network accessible to both. -We have found that not all access points -are suitable; you may need to use an access point -whose firewall is configured properly to support adb.
- -Note: If you are attempting to connect -to a Wear device, force it to connect to Wi-Fi by shutting off Bluetooth -on the phone connected to it.
--$ adb tcpip 5555 --
-$ adb connect <device-ip-address> --
-$ adb devices -List of devices attached -<device-ip-address>:5555 device -- -
-You're now good to go! -
- --If the adb connection is ever lost: -
- --adb kill-server --and then start over from the beginning. -
- Important: Support for the Android Developer Tools (ADT) in Eclipse has ended, - per our announcement. You should migrate your app development projects to - Android Studio as soon as possible. For more information on transitioning to Android Studio, see - Migrating from Eclipse ADT. -
- -Formerly the official IDE solution for Android development, Android Developer Tools (ADT) - is a plugin for Eclipse that provides GUI-based access to many of the command-line SDK tools, - along with a UI design tool for rapid prototyping, designing, and building of your app's - user interface.
- -As with ADT, support for the Ant - tool for building from the command line has ended. - Gradle is now the supported method - of building Android apps. -
diff --git a/docs/html/tools/help/am-allocation.jd b/docs/html/tools/help/am-allocation.jd deleted file mode 100644 index 20570c3be2e1cfdd73d1f8c76a2a21aa6d887593..0000000000000000000000000000000000000000 --- a/docs/html/tools/help/am-allocation.jd +++ /dev/null @@ -1,220 +0,0 @@ -page.title=Allocation Tracker -parent.title=Android Monitor -parent.link=android-monitor.html -meta.tags="android, performance, profiling, tools, monitor" -page.tags="android", "performance", "profiling", "tools", "monitor" -page.metaDescription=Use the Memory Monitor to capture allocation data about your app. The Allocation Tracker displays each method responsible for an allocation, as well as the allocation size and number of instances. -page.image=tools/help/thumbnails/am_alloctracker.png -page.article=true - -@jd:body - -Android Studio allows you to track memory allocation as it monitors memory use. Tracking memory - allocation allows you to monitor where objects are being allocated when you perform certain - actions. Knowing these allocations enables you to adjust the method calls related to those actions - to optimize app performance and memory use.
- -The Allocation Tracker does the following:
-However, it takes time and experience to learn to interpret the output from this tool.
- -- The Allocation Tracker looks similar to the following figure: -
-
-- - -
The tool displays the following information:
- -| Column | -Description | -
|---|---|
| Method | -The Java method responsible for the allocation. | -
| Count | -Total number of instances allocated. | -
| Size | -The total amount of allocated memory in bytes. | -
To examine allocation data:
-
. again to
- deselect it and end the snapshot. The Memory Monitor displays the period when it took the snapshot. In the following - figure, you can see the snapshot period, as shown on the left. By comparison, when you dump the - Java heap, the Memory Monitor displays just the point where the heap snapshot was taken, as - shown on the right.
-
-
-Android Studio creates the heap snapshot file with the
- filename package_yyyy.mm.dd_hh.mm.ss.alloc using the activity package (or
- project) name, year, month, day,
- hour, minute, and second of the capture, for example,
- com.android.calc_2015.11.17_14.58.48.alloc.
to display a visual representation of the data.
- After you capture allocation data, Android Studio automatically stores it so -you can view it again.
-To view an allocation tracking file in the Allocation Tracker:
- - -
in the main window.Or select View > Tools Windows > -Captures.
-The Captures window appears.
-To sort allocation data:
-For some items displayed in the Allocation Tracker, you can view the Java source.
-To display Java source:
-
. The source code appears in the Code Editor.
- - -You can rename, locate, and delete an allocation tracking file from within -Android Studio.
- -If you rename a file from within Android Studio, it continues to appear in the Captures - window.
-To rename an allocation tracking file:
-You can quickly discover where Android Studio stored allocation tracking files on disk.
- - -To locate an allocation tracking file from Android Studio:
-Android Studio opens an operating system file browser displaying the location where the file - resides.
-Note: If you move an allocation tracking file, Android Studio - no longer displays it in the Captures window. To display the file, use - File - > Open. Also, rename the file from the Captures - window and not in the operating system file browser.
- -To delete an allocation tracking file:
-Android Studio deletes the file from the Captures dialog and from disk.
-
- Android Monitor has a main window that contains the logcat, Memory, CPU, GPU, and Network
- Monitors. From this window, you can select a device and app process to work with, terminate an
- app, collect dumpsys system information, and create screenshots and videos of the
- running app.
-
- Before you start using Android Monitor, you need to set up your environment, as well as the - hardware device or emulator. All of the monitors require the following: -
-- All but the logcat Monitor have these additional requirements: -
-debuggable property to true in the manifest or
- build.gradle file (it’s initially set by default).
- - The GPU Monitor has this requirement as well: -
-- The Network Monitor and the Video Capture tool work with a hardware device - only, not the emulator. -
- - - -- Android Monitor is integrated into the Android Studio main window: -
- -
,
- which by default is at the bottom of the main window.
- again.
- - Note: If you don't see the sidebar buttons, you can - display them by selecting View > - Tool Buttons. -
-- Android Monitor looks like the following figure: -
-
-
-- After you've met the prerequisites and optionally connected a hardware device, you're ready - to profile an app in Android Monitor: -
- -- By default, Android Monitor displays data for your most recently run app. You can switch to - another device and app as needed. In addition to currently running apps, you can view - information about apps that are no longer running so you can continue to see any information - about them that you gathered previously. -
- -- At the top of the Android Monitor main window are two menus listing devices and processes. To - switch to another device, process, or both: -
- -- The Device menu lists the devices and emulators that are running or have run during your - current session. There are various status messages that can appear in the Device menu: -
- -- The Process menu lists the processes that are running or have run during your current session. If - a process is no longer running, the menu displays a status of DEAD. -
-- You can rearrange the Android Monitor windows for optimal viewing during your - tests: -
-
or Move Monitor Down
- 
.
- 
- or Maximize Monitor
- 
.
- - To rearrange the logcat and Monitors tabs: -
-
> Floating Mode.
- 
icon. To make it reappear, click Restore Monitors View
-
- or the Restore logcat View
- 
- on the far right of the row of tabs.
- - To stop an app you’ve run from Android Studio: -
- -
.
- - The process status changes to DEAD in the Processes menu. The emulator or device - continues to run, but the app closes. Any running monitors in Android Monitor stop. -
-- To remove an app from a device you use for development, use the normal uninstall procedure on the - device. -
- -- If you run a new version of an app from Android Studio that’s been already installed on a - hardware device, the device displays an Application Installation Failed dialog. Click - OK to install the new version of the app. -
- -- From the Android Monitor main window, you can also do the following: -
- -dumpsys system information.
- - The CPU Monitor lets you easily monitor the central processing unit (CPU) usage of your app. It - displays CPU usage in real time and displays the percentage of total CPU time (including all cores) - used in user and kernel mode. In user mode, the code must use system APIs to access hardware or - memory, has access to virtual memory addresses only, and crashes are usually - recoverable. In kernel mode, the code can directly access - hardware, including physical memory addresses; crashes halt the device. -
- - -- To display an app running on a particular device or emulator in the CPU Monitor: -
- -
to deselect it.
- - The CPU Monitor starts to display any CPU usage. - In the graph, the y-axis displays the percentage of CPU used. The x-axis records the time elapsed - and starts with seconds, and then minutes and seconds, and so on. -
-
- again to select
- it.
- - You can capture a record of the changes on the call stack during a particular - time period while the CPU Monitor is running. For more information, see - Method Trace. -
- - - - diff --git a/docs/html/tools/help/am-gpu.jd b/docs/html/tools/help/am-gpu.jd deleted file mode 100644 index fb140ad8b9b2cdfd022dd59732fa3b538693f063..0000000000000000000000000000000000000000 --- a/docs/html/tools/help/am-gpu.jd +++ /dev/null @@ -1,89 +0,0 @@ -page.title=GPU Monitor -parent.title=Android Monitor -parent.link=android-monitor.html -meta.tags="android, performance, profiling, tools, monitor" -page.tags="android", "performance", "profiling", "tools", "monitor" -page.metaDescription=Use the GPU Monitor for a visual representation of how much time it takes to render the frames of a UI window. Use this information to optimize the code that displays graphics and conserve memory. -page.image=tools/help/thumbnails/am-gpumon.png -page.article=true - -@jd:body - -- The GPU Monitor gives you a quick visual representation of how much time it takes to render the - frames of a UI window. It profiles the amount of time it takes for the render thread to prepare, - process, and execute the draw commands. The GPU Monitor can help you to: -
- -- For example, if displaying a static photo continues to take Graphics Processor Unit - (GPU) resources long after it has finished - drawing on the screen, that’s a likely candidate for optimization. -
- - -- To display an app running on a particular device or emulator in the GPU Monitor: -
- - to deselect it.
- - Any GPU usage begins to appear in the GPU Monitor: -
-
-
-- The y-axis is the amount of time it takes the GPU to execute, process, prepare, and draw frames, - in milliseconds. The x-axis records the time elapsed; it starts with seconds, and then minutes - and seconds, and so on. -
- - again to select
- it.
- - When you're monitoring memory usage in the Memory Monitor you can, at the same time, dump a - snapshot of the Java heap to an Android-specific Heap/CPU Profiling (HPROF) file. The HPROF Viewer - displays classes, instances of each class, and a reference tree to help you track memory usage - and find memory leaks. HPROF is a binary heap dump format originally supported by J2SE. -
-The Java heap display does the following:
- -- However, you have to look for changes over time yourself by tracking what's happening in the - graph. -
- -- The HPROF Analyzer finds the following potential issues: -
- -- A dominator is at the top of a tree. If you remove it, you also remove the branches of the tree - it dominates, so it’s a potential way to free memory. -
- -- The HPROF Viewer looks similar to the following figure: -
-
-- The tool displays the following information: -
- -| Column | -Description | -
|---|---|
| Class Name | -The Java class responsible for the memory. | -
| Total Count | -Total number of instances outstanding. | -
| Heap Count | -Number of instances in the selected heap. | -
| Sizeof | -Size of the instances (currently, 0 if the size is variable). | -
| Shallow Size | -Total size of all instances in this heap. | -
| Retained Size | -Size of memory that all instances of this class is dominating. | -
| Instance | -A specific instance of the class. | -
| Reference Tree | -References that point to the selected instance, as well as references pointing to the - references. | -
| Depth | -The shortest number of hops from any GC root to the selected instance. | -
| Shallow Size | -Size of this instance. | -
| Dominating Size | -Size of memory that this instance is dominating. | -
If you click Capture Analysis, the HPROF Analyzer appears:
-
-You can detect leaked activities and find duplicate strings with the HPROF Analyzer.
- -- To examine a snapshot of the Java heap: -
- -
.
-
- When the icon on the Memory Monitor display changes from
- 
to
- 
, the file is ready. Android Studio creates the heap snapshot
- file with the
- filename package_yyyy.mm.dd_hh.mm.ss.hprof using
- the activity package (or project) name, year, month, day, hour, minute, and second of the
- capture, for example,
- com.android.calc_2015.11.17_14.58.48.hprof.
-
- The HPROF Viewer appears. -
-After you do a heap dump, Android Studio automatically stores it so you can view it again. -
-To view an HPROF file in the HPROF Viewer:
- - in the main window.Or select View > Tools Windows > -Captures.
-The Captures window appears.
-- The HPROF Viewer appears. -
- - -The following steps outline the typical workflow:
-You can detect leaked activities and find duplicate strings with the HPROF Analyzer. -
-To use the HPROF Analyzer:
-.hprof file to display it in the
- HPROF Viewer. The HPROF Analyzer appears to the right of the HPROF Analyzer, by default.
- - - -
.To sort heap dump data:
-For some items displayed in the HPROF Viewer, you can go straight to its -source code. -
-To display Java source:
-The source code appears in the Code Editor.
-You can rename, locate, and delete an HPROF file from within Android Studio. -You can also convert it to standard HPROF format to use with other analysis -tools.
- -If you rename a file from within Android Studio, it continues to appear in -the Captures window.
-To rename an HPROF file:
-You can quickly discover where Android Studio stored HPROF files on disk.
- - -To locate an HPROF file on disk:
-Android Studio opens an operating system file browser displaying the location where the file - resides.
-Note: If you move an HPROF file, Android Studio no longer - displays it in the Captures window. To display it, use - File > Open. Also, if you want to rename the file, do it - from the Captures window and not in the operating system file browser.
- -To delete a heap dump file:
-Android Studio deletes the file from the Captures dialog and from disk.
-You can convert an HPROF file to standard format so you can use it outside of Android Studio with - other analysis tools.
-To convert an HPROF file:
-Android Studio creates a binary HPROF file in the location you specified.
-- The Android logging system provides a mechanism for collecting and viewing system debug output. - The logcat Monitor displays system messages, such as when a garbage collection occurs, as well as - messages that you added to your app by using the Log class. - It displays messages in real time and also keeps a history so you can view older - messages. -
- -- To display just the information of interest, you can create filters, modify how much information - is displayed in messages, set priority levels, display messages produced by app code - only, and search the log. By default, the logcat Monitor shows the log output related to the - most recently run app only. -
- -- When an app throws an exception, the logcat Monitor shows a message followed by the associated - stack trace containing links to - the code. This feature can help you fix errors and improve app operation. -
- -- Every Android log message has a tag and a priority associated with it. The tag of a system - log message - is a short string indicating the system component from which the message originates (for example, - {@link android.app.ActivityManager}). A user-defined tag can be any string that you find helpful, - such as the name of the current class (the recommended tag). You define it in a - {@link android.util.Log} method call, for example: -
- --Log.d(tag, message); --
- The priority is one of the following values: -
- -- The log message format is: -
- --date time PID-TID/package priority/tag: message -- -
- For example, the following log message has a priority of V and a tag of
- AuthZen:
-
-12-10 13:02:50.071 1901-4229/com.google.android.gms V/AuthZen: Handling delegate intent. --
- PID stands for process identifier and TID is thread identifier; they can be the same if there’s - only one thread. -
- -- To display the log messages for a particular app: -
- -- By default, the logcat Monitor displays just the log messages for your app running on the - device or emulator: -
-
-- To change this default, see Filtering logcat Messages. -
-- You can control how many messages appear in the logcat Monitor by setting the log level. You can - display all messages, or just the messages indicating the most severe conditions. -
- -- Remember that the logcat Monitor continues to collect all messages regardless of the log level setting. - The setting just determines what the logcat Monitor displays. -
- -- To set the log level: -
- -- To search the messages currently displayed in the logcat Monitor: -
- -
.
- - The logcat Monitor display changes accordingly. -
- - -- One way to reduce the log output to a manageable level is to restrict it by using a filter. -
- -- Note: The filter applies to your full logcat history, not just those messages - currently displayed in the logcat Monitor. Make sure your other display options are set - appropriately so you can see the filter output you want to examine. -
- -- To define and apply a filter: -
- -- After you define filters, you can also select them in the menu. To remove them from the - menu, delete them. -
- -- To remove a filter, select it in the left pane and click -. -
- -- If you don't think you see the log messages you want, try selecting - No filters and searching for particular - log messages. -
-- To customize the header display to show just the information you’re interested - in: -
- -
- to see the entire
- message and prevent it from running off of the right edge.
-
- to specify
- elements of the messages that you want to show or hide, and then click
- OK.
- - For more information about message elements, see logcat Message Format. -
- -- When the app throws an exception, the message includes a stack trace of method calls. - logcat - Monitor lets you quickly locate stack traces in the log and view the associated code - in the Code Editor. If needed (and possible), the decompiler derives source code that - you can view. -
-- To move up and down the stack trace, and view the associated code in the Code Editor: -
-
- to move to the
- previous method in relation to the current position in the log.
- 
- to move to
- the next method in relation to the current position in the log.
- - Clicking a particular message stops the display of messages. -
-- To quickly move to - the end of the log to see the real-time message flow: -
- -
.
- - To preserve log information, you can send the log to a printer, write the log to a PDF file, or - copy and paste the log into a text file. -
-- To print the log or write it to a PDF file: -
-
.
- - You can set the parameters to send the log to a printer or write it to a PDF file. -
-- To copy the log to a text file: -
-Press Ctrl+A (⌘A) to select all.
-- To clear (flush) the entire log: -
-
.
- - If there's a problem and the log is no longer progressing, you can restart the log: -
- -
.
- - Android Studio provides a Memory Monitor so you can more easily monitor app performance and - memory usage to find deallocated objects, locate memory leaks, and track the amount of memory the - connected device is using. The Memory Monitor reports how your app allocates memory and helps you - to visualize the memory your app uses. It lets you: -
- -- To profile and optimize memory use, the typical workflow is to run your app and do the following: -
- -- The Java heap data shows in real-time what types of objects your application has allocated, how - many, and their sizes on the heap. Viewing the heap helps you to: -
- -- Allocation tracking records app memory allocations and lists all allocations for the - profiling cycle, including the call stack, size, and allocating code. It helps you to: -
- -
- When you dump the Java heap, the Memory Monitor creates an Android-specific Heap/CPU Profiling
- (HPROF) file that you can view in the HPROF Viewer. The HPROF Viewer indicates a garbage
- collection root with the 
icon (and a depth of zero)
- and a
- dominator with the 
icon.
-
- There are several kinds of garbage collection roots in Java: -
- -- The HPROF file provides the list of roots to the HPROF Viewer. -
- -- A dominator tree traces paths to objects created by the app. An object dominates another object - if the only way to reach the other object is, directly or indirectly, through the dominator - object. When you examine objects and paths created by an app in an effort to optimize memory use, - try to remove objects that are no longer needed. You can release a dominator object to - release all subordinate objects. For example, in the following figure, if you were to - remove object B, that would also release the memory used by the objects it dominates, which are - objects C, D, E, and F. In fact, if objects C, D, E, and F were marked for removal, but object B - was still referring to them, that could be the reason that they weren’t released. -
- -
-
-- An app performs better if it uses memory efficiently and releases the memory when it’s no longer - needed. - Memory leaks that are large or that grow over time are the most important to correct. -
- -- One way to optimize memory usage is to analyze large arrays. For example, can you reduce the size - of individual elements in the array to save memory? -
- -- Another area that deserves attention is objects that the app no longer needs but continues to - reference. You can gather heap dumps over different periods of time and compare them to determine - if you have a growing memory leak, such as an object type that your code creates multiple times - but doesn’t destroy. These objects could be part of a growing array or an object tree, for - example. To track down this problem, compare the heap dumps and see if you have a particular - object type that continues to have more and more instances over time. -
- -- Continually growing object trees that contain root or dominator objects can prevent subordinate - objects from being garbage-collected. This issue is a common cause of memory leaks, out-of-memory - errors, - and crashes. Your app could have a small number of objects that are preventing a large number of - subordinate objects from being destroyed, so it runs out of memory quickly. To find these issues, - get a heap dump and examine the amount of memory held by root and dominator objects. If the - memory is substantial, you’ve likely found a good place to start optimizing your memory use. -
- -- As you start narrowing down memory issues, you should also use the Allocation Tracker to get a - better understanding of where your memory-hogging objects are allocated. The Allocation Tracker - can be valuable not only for looking at specific uses of memory, but also for analyzing critical - code paths, such as loading and scrolling. For example, tracking allocations when flinging a list - in your app - allows you to see all of the allocations that need to be done for that behavior, what thread they - are on, and where they came from. This information is extremely valuable for tightening up these - paths to reduce the work they need and improve the overall smoothness of the UI. -
- -- It’s useful to examine your algorithms for allocations that are unnecessary or that create the - same object many times instead of reusing them. For example, do you create temporary objects and - variables within recursive loops? If so, try creating an object or variable before - the loop for use within the loop. Otherwise, your app might needlessly allocate many objects and - variables, depending on the number of recursions. -
- -- It’s important to perform allocation tests on portions of your code that create the most and - largest objects, as those areas offer the most optimization opportunities. In addition to unit - tests, you should test your app with production-realistic data loads, especially those algorithms - that are data-driven. Also, make sure to account for the app caching and startup phase, which can - sometimes be slow; allocation analysis is best done after that phase to produce accurate results. -
- -- After you optimize code, be sure to test that it worked. You need to test under different load - conditions and also without running the Memory Monitor tools. Compare results before and after - optimization to make sure that performance has actually improved. -
- -- Android Monitor uses the Virtual Machine (VM) that the device or emulator uses: -
- -- The VM handles garbage collection. The Dalvik VM uses a mark-and-sweep scheme for garbage - collection. The ART VM uses a generational scheme, combined with mark-and-sweep when memory needs - a more thorough garbage collection, such as when memory becomes excessively fragmented. The - logcat Monitor displays some messages that indicate the type of garbage collection that occurred - and why. -
- -- Memory Monitor results can vary between the different VMs. As a result, if you’re supporting both - VMs, you might want to test with both. In addition, the VMs available for different API levels - can have different behavior. For example, the Dalvik VM in Android 2.3 (API level 10) and lower - uses externally allocated memory while higher versions allocate in the Dalvik heap only. -
- -- You can’t reconfigure the Dalvik and ART VMs to tune performance. Instead, you should examine - your app code to determine how to improve its operation, for example, reducing the size of very - large arrays. -
- -- There are programmatic ways to manipulate when the VM performs garbage collection, although it’s - not a best practice. These techniques can be specific to the VM. For more information, see - Addressing - Garbage Collection (GC) Issues and Investigating Your RAM - Usage. -
- -- The ART VM adds a number of performance, development, and debugging improvements over the Dalvik - VM. For more information, see ART and Dalvik. -
- -- To display an app running on a particular device or emulator in the Memory Monitor: -
- - to deselect it.
- - In the graph, the y-axis displays the free and allocated RAM in megabytes. The x-axis shows the - time elapsed; it starts with seconds, and then minutes and seconds, and so on. The amount of free - memory, measured in megabytes, - is shown in a light color, and allocated memory is a darker color. When there’s a sharp drop in - allocated memory, that indicates a garbage collection event.
- - - -
- To force a garbage collection event, click Initiate GC 
.
-
In the following figure, the VM initiated the first garbage collection event, while the - developer forced the second. -
-
-
- - The graph can show you potential issues: -
- -- For example, you might see the following signs of problems: -
- - again to select it.
- - Normally, VMs perform garbage collection only when absolutely needed, since it’s expensive. - However, it can be useful to force garbage collection in certain circumstances. For example, when - locating memory leaks, if you want to determine whether a large object was successfully released - already, you can initiate garbage collection much more aggressively than usual. -
- -- To force a garbage collection event: -
- -.
- - You can take snapshots while the Memory Monitor is running or paused: -
- -- You can start a method trace from the CPU Monitor. It lets you view the call stack and timing - information for your app. This information can help you optimize and debug your app. -
- -- The method trace looks similar to the following figure: -
-
-
-
-The display shows the following information:
- -| Field | -Description | -
|---|---|
| Name | -The name of the method. | -
| Invocation Count | -How many times the method was called. | -
| Inclusive Time (microseconds) | -Time spent in the method and all of its children, either wall clock or thread time, - depending on your selection in the x-axis menu. | -
| Exclusive Time (microseconds) | -Time spent just in the method (excluding time spent in its children), either wall clock - or thread time, depending on your selection in the x-axis menu. | -
Note: Running the method trace significantly affects CPU timings. - Use the method trace to understand the flow of the program, but not for performance timings.
- -- To perform a method trace: -
- -
to
- select it.
- to
- deselect it.
- - The method trace appears in the Code Editor area. -
- -
- Android Studio creates the method trace file
- with the filename package_yyyy.mm.dd_hh.mm.ss.trace
- using the activity package (or project) name, year, month, day, hour, minute, and second of
- the capture, for example,
- com.android.calc_2015.11.17_14.58.48.trace.
-
- The graphic represents the wall clock or thread time for each method. Hover the cursor - over the display to receive information about the method. This information also appears - in the table. -
-- After you do a method trace, Android Studio automatically stores it so you can view it - again.
- -To examine a saved method trace: -
- - in the main window.
- Or select View > Tools Windows > - Captures.
- -- The Captures window appears. -
- -- You can sort the data by method name, count, inclusive time, and exclusive - time.
- -To sort method trace data:
- - -You can rename, locate, and delete a method trace file from within Android -Studio.
- -- Rename a method trace file from within Android Studio so it - continues to appear in the Captures window.
- -To rename a method trace file: -
- -- You can quickly discover where Android Studio stored method trace files on - disk.
- -To locate a method trace file on disk: -
- - - -- Android Studio opens an operating system file browser displaying the location where the file - resides. -
-- Note: If you move a method trace file, Android Studio no longer displays the file - in the Captures window. To display it, use File > - Open. Also, rename a file from the Captures - window and not in the operating system file browser. -
- -- To delete a method trace file: -
- -- Android Studio deletes the file from the Captures dialog and from disk. -
\ No newline at end of file diff --git a/docs/html/tools/help/am-network.jd b/docs/html/tools/help/am-network.jd deleted file mode 100644 index 812999207f7bbcee98ebb3d16b58fc1a4c1a0e27..0000000000000000000000000000000000000000 --- a/docs/html/tools/help/am-network.jd +++ /dev/null @@ -1,87 +0,0 @@ -page.title=Network Monitor -parent.title=Android Monitor -parent.link=android-monitor.html -meta.tags="android, performance, profiling, tools, monitor" -page.tags="android", "performance", "profiling", "tools", "monitor" -page.metaDescription=Use the Network Monitor to analyze network requests, including how and when your app transfers data. Preserve battery life by optimizing network use. -page.image=tools/help/thumbnails/am-networkmon.png -page.article=true - -@jd:body - -- The Network Monitor makes it possible to track when your application is making network requests. - Using this tool, you can monitor how and when your app transfers data, and optimize the underlying - code appropriately. -
- -- By monitoring the frequency of data transfers, and the amount of data transferred during each - connection, you can identify areas of your app that can be made more efficient and use less - battery power. - Generally, you should look for short spikes that can be delayed, or that could cause a later - transfer to be preempted. -
- - -- To display an app running on a particular device in the Network Monitor: -
- -Connect a hardware device; the Network Monitor doesn't monitor an emulator. -
- to deselect it.
- - Any network traffic begins to appear in the Network Monitor: -
-
-- The Network Monitor adds up the amount of time it takes for the device to transmit and receive - kilobytes of data. - The y-axis is in kilobytes per second. The x-axis starts with seconds, and then minutes and - seconds, and so on. -
- again to
- select it.
- - You can take a PNG screenshot of the display on a connected device or the emulator. You can use - the images for your marketing materials as well as for debugging, for example. -
- - -- To take a screen capture: -
-
in the
- Android Monitor toolbar.
- The screenshot appears in a Screenshot Editor window.
- -
-
- The screenshot file appears in the Code Editor area.
-dumpsys information about your app. View activity manager, package, memory usage, and graphics state information.
-page.image=tools/help/thumbnails/am_sysinfo.png
-page.article=true
-@jd:body
-
- You can capture dumpsys output from within Android Monitor and
- display the file in the Code Editor. The Captures window lists the
- system information files so you can retrieve the information later for
- analysis.
-
- To capture and view a snapshot of system information: -
- -
- and then select a menu item.
-
- The menu items display different types of dumpsys
- output:
-
dumpsys activity
- dumpsys package
- dumpsys
- meminfo
- dumpsys
- procstats
- dumpsys gfxinfo
- - The information appears in an editable text file in the Code Editor. -
-
-Android Studio creates the system information file with the
- filename package_yyyy.mm.dd_hh.mm.ss.txt using the
- activity package (or project) name, year, month, day,
- hour, minute, and second of the capture, for example,
- com.android.calc_2015.11.17_14.58.48.txt.
-After you take a snapshot of system information, Android Studio automatically -stores it so you can view it again.
- -To examine a saved system information file:
- - in the main window.
- Or select View > Tools Windows > - Captures.
- -- The Captures window appears. -
- -You can rename, locate, and delete a system information file from within -Android Studio.
- -- Rename a system information file from within Android Studio so it - continues to appear in the Captures window.
- -To rename a system information file: -
- -- You can quickly discover where Android Studio stored system information files - on disk.
- -To locate a system information file on disk: -
- - - -- Android Studio opens an operating system file browser displaying the location - where the file resides. -
-- Note: If you move a system information file, Android Studio - no longer displays the file - in the Captures window. To display it, use File > - Open. Also, rename a file from the Captures - window and not in the operating system file browser. -
- -- To delete a system information file: -
- -- Android Studio deletes the file from the Captures dialog and from - disk. -
diff --git a/docs/html/tools/help/am-video.jd b/docs/html/tools/help/am-video.jd deleted file mode 100644 index 5ecdd11ad40a603e3e4b533dd8c18b7d5f2f9395..0000000000000000000000000000000000000000 --- a/docs/html/tools/help/am-video.jd +++ /dev/null @@ -1,78 +0,0 @@ -page.title=Video Capture -parent.title=Android Monitor -parent.link=android-monitor.html -meta.tags="android, performance, profiling, tools, monitor" -page.tags="android", "performance", "profiling", "tools", "monitor" -page.metaDescription=Use the Video tool to make a video of the display on a hardware device. -page.image=tools/help/thumbnails/am_video.png -page.article=true -@jd:body - - -- Android Studio lets you record an MP4 video from your hardware device for a maximum of three - minutes. You can use the video for your marketing materials as well as for debugging, for - example. -
-
-
-
-
-- To record a video from a hardware device: -
-
in the
- Android Monitor toolbar.
- The screenshot appears in a Screenshot Editor window.
- -- Android Monitor helps you to profile the performance of your apps so you can optimize, debug, and - improve them. It lets you monitor the following aspects of your apps from a hardware device or - the Android Emulator: -
- -Android Monitor provides various tools that provide real-time information about your app. It - lets you capture data as your app runs and stores it in a file that you can analyze in various - viewers. You can also capture screen shots and videos of your app as it runs.
- -View log messages — in real time and historically — which is useful for debugging.
- -Visualize the behavior and performance of your app.
- -Android Monitor lets you capture various types of data about your app while it's running and - stores it in a file, which you can access whenever is convenient. - It lists these files in the Captures window.
- -Create screen captures and videos of your app to help with marketing and debugging. -
- -To begin using Android Monitor, start with Android Monitor Basics. -
- - diff --git a/docs/html/tools/help/android.jd b/docs/html/tools/help/android.jd deleted file mode 100755 index fa359e99e559e7464f65438a9a872ef910d25da4..0000000000000000000000000000000000000000 --- a/docs/html/tools/help/android.jd +++ /dev/null @@ -1,418 +0,0 @@ -page.title=android -parent.title=Tools -parent.link=index.html -@jd:body - -{@code android} is an important development tool that lets you:
- -If you are using Android Studio, the android tool's features are
-integrated into the IDE, so you should not need to use this tool directly.
Note: The documentation of options below is not exhaustive
-and may be out of date. For the most current list of options, execute android
---help.
android [global options] action [action options]- -
-s-h-v| Action | - -Option | - -Description | - -Comments | -
|---|---|---|---|
avd |
-
- None | - -Launch the AVD Manager | - -- |
sdk |
-
- None | - -Launch the Android SDK Manager | - -- |
create avd |
-
- -n <name> |
-
- The name for the AVD. | - -Required | -
-t <targetID> |
-
- Target ID of the system image to use with the new AVD. To obtain a list of available
- targets, use android list targets |
-
- Required | -|
-c <path>|<size>[K|M] |
-
- The path to the SD card image to use with this AVD or the size of a new SD card image to
- create for this AVD. For example, -c path/to/sdcard or -c
- 1000M. |
-
- - | |
-f |
-
- Force creation of the AVD | - -- | |
-p <path> |
-
- Path to the location at which to create the directory for this AVD's files. | - -- | |
-s <name>|<width>-<height> |
-
- The skin to use for this AVD, identified by name or dimensions. The android
- tool scans for a matching skin by name or dimension in the skins/ directory of
- the target referenced in the -t <targetID> argument. For example, -s
- HVGA-L |
-
- - | |
delete avd |
-
- -n <name> |
-
- The name of the AVD to delete | - -Required | -
move avd |
-
- -n <name> |
-
- The name of the AVD to move | - -Required | -
-p <path> |
-
- Path to the location at which to create the directory for this AVD's files. | - -- | |
-r <new-name> |
-
- New name of the AVD if you want to rename it | - -- | |
update avd |
-
- -n <name> |
-
- The name of the AVD to move | - -Required | -
| Action | - -Option | - -Description | - -Comments | -
|---|---|---|---|
create project |
-
- -n <name> |
-
- The name for the project | - -Required | -
-t <targetID> |
-
- Target ID of the system image to use with the new AVD. To obtain a list of available
- targets, use android list targets |
-
- Required | -|
-k <path>|<size>[K|M] |
-
- Package namespace | - -Required | -|
-a |
-
- Name for the default Activity class | - -Required | -|
-p <path> |
-
- Location of your project directory | - -Required | -|
update project |
-
- -n <name> |
-
- The name of the project to update | - -- |
-p <path> |
-
- Location path of the project | - -Required | -|
-l <library path> |
-
- Location path of an Android Library to add, relative to the main project | - -- | |
-s <subprojects> |
-
- Update any projects in subfolders such as test projects | - -- | |
-t <targetID> |
-
- Target id to set for the project | - -- | |
create test-project |
-
- -n <name> |
-
- The name of the project | - -- |
-p <path> |
-
- Location path of the project | - -Required | -|
-m <main> |
-
- The name of the project | - -Required | -|
update test-project |
-
- -p <path> |
-
- Location path of the project to test, relative to the new project | - -Required | -
-m <main> |
-
- The main class of the project to test | - -Required | -|
create lib-project |
-
- -k <packageName> |
-
- (Required) Package name of the library project | - -Required | -
-p <path> |
-
- Location path of the project | - -Required | -|
-t <targetID> |
-
- Target ID of the library project | - -Required | -|
-n <name> |
-
- The name of the project | - -Required | -|
update lib-project |
-
- -p <path> |
-
- Location path of the project | - -Required | -
-l <libraryPath> |
-
- Location path of an Android Library to add, relative to the main project | - -- | |
-t <name> |
-
- Target ID of the library project | - -- | |
create uitest-project |
- -n <name> |
- The name of the UI test project | -- |
-t <name> |
-
- Target ID of the UI test project | - -Required | -|
-p <path> |
-
- Location path of the UI test project | - -Required | -
update adbupdate sdkAndroid Studio helps you add support for URLs, app indexing, and search -functionality to your apps. - These features can help to drive more traffic to your - app, discover which app content is used most, make it easier for users to find content in an - installed app, and attract new users.
- -To use Android Studio to add support for URL, app indexing, and search -features to your app:
- -Intent filters and the App Indexing API are ways to implement URL support -and app indexing, but - there are other possible implementations as well. See - Alternate Android Indexing Methods - for more information.
- -Android Studio can create a basic intent filter in your manifest that you can customize to - define URLs for your app. You can then write Java code in an activity to handle the - intent. This implementation lets users directly open the specified app activity by - clicking a URL. Users can see the URLs in google.com in a browser, in the - Google Search app, and in Google Now on Tap.
- -After setting up URL support for your app, you can associate your website -with your app by using - the Google Search Console and Google Play Developer Console. Afterward, Google indexes your app - for URLs defined in - your intent filters and begins to include them in search results. In addition, you can optionally - exclude app content from Google Search. After you associate a website with your app, features - such as Now on Tap and enhanced search result display (like including your app icon) - become available.
- -As an alternative to associating your app with a website, - for Android 6.0 (API level 23) and higher, you can add - default handlers and verification for URLs - instead.
- -Chrome displaying google.com serves search results with URLs that are accessible to both - signed-in users and those who aren't. Google Search app users must be signed in to see URLs - in their search results.
- -Next, if you want to support additional search features, such as autocompletions, you can - add App Indexing API code to your app. Android Studio can create skeleton code in an activity - that you can then customize to support app indexing. The App Indexing API allows app indexing - even if - Googlebot - can’t get content from your app.
- -Android Studio helps you test your code with the following features:
- -The details for implementing URL support and app indexing are described next. - - -
To use Android Studio features to add an intent filter defining a URL:
- -AndroidManifest.xml file to open it
- in the Code Editor.<activity> element, click in the left column so the light bulb
- 
appears. Click
-
- and select Create URL.<activity> element and select Generate
- > URL.The Code Editor adds skeleton code using the - intention action and - generate code mechanisms.
- -The Code Editor adds an intent filter similar to the following:
--<!-- ATTENTION: This intent was auto-generated. Follow instructions at - https://g.co/AppIndexing/AndroidStudio to publish your URLs. --> -<intent-filter> - <action android:name="android.intent.action.VIEW" /> - - <category android:name="android.intent.category.DEFAULT" /> - <category android:name="android.intent.category.BROWSABLE" /> - <!-- ATTENTION: This data URL was auto-generated. - We recommend that you use the HTTP scheme. - TODO: Change the host or pathPrefix as necessary. --> - <data - android:host="www.example.com" - android:pathPrefix="/gizmos" - android:scheme="http" /> -</intent-filter> -- -
<data> element
- and optionally the <category> element, as needed.We recommend that you define a <data> element that supports URLs that you’ll
- add in the future. In the previous sample code, for example, Google will index any URLs starting
- with http://www.example.com/gizmos. Also, remember to
- include a URL for your app home screen so it’s included in search results.
The URLs you specify in your intent filters can be the same as the URLs of -the comparable pages on your website.
- -To support Google Search for your URLs:
-Alternatively, for Android 6.0 (API level 23) and higher, add - link default handling and verification.
-To test and debug your links, you can use the following Android Studio features:
-In addition, you can - preview your APK in the Google Search Console - to test your URLs, whether the app is associated with a website or not.
- - - -After adding URL support to your app, you can add App Indexing API code to -an activity to support additional search features.
- -To add App Indexing API code to an activity:
- appears.
- Click
- and select Insert App Indexing API Code.The Code Editor adds skeleton code using the - intention action and - generate code - mechanisms.
- -If you don’t see the App Indexing API Code menu item, make sure your cursor is - within an activity, and check your code for App Indexing API methods. The Code Editor can insert - skeleton Java code into an activity in the following circumstances:
- -onStart() method, or the onStart()
- method doesn’t contain an AppIndexApi.start() or AppIndexApi.view()
- call.onStop() method, or the onStop()
- method doesn’t contain an AppIndexApi.end() or AppIndexApi.viewEnd()
- call.The Code Editor adds Java code similar to the following:
-
- /**
- * ATTENTION: This was auto-generated to implement the App Indexing API.
- * See https://g.co/AppIndexing/AndroidStudio for more information.
- */
- private GoogleApiClient client;
-
- // ATTENTION: This was auto-generated to implement the App Indexing API.
- // See https://g.co/AppIndexing/AndroidStudio for more information.
- client = new GoogleApiClient.Builder(this).addApi(AppIndex.API).build();
- }
-
-
- @Override
- public void onStart() {
- super.onStart();
-
- // ATTENTION: This was auto-generated to implement the App Indexing API.
- // See https://g.co/AppIndexing/AndroidStudio for more information.
- client.connect();
- Action viewAction = Action.newAction(
- Action.TYPE_VIEW, // TODO: choose an action type.
- "Main Page", // TODO: Define a title for the content shown.
- // TODO: If you have web page content that matches
- // this app activity's content,
- // make sure this auto-generated web page URL is correct.
- // Otherwise, set the URL to null.
- Uri.parse("http://www.example.com/gizmos"),
- // TODO: Make sure this auto-generated app URL is correct.
- Uri.parse("android-app://com.example/http/www.example.com/gizmos")
- );
- AppIndex.AppIndexApi.start(client, viewAction);
- }
-
- @Override
- public void onStop() {
- super.onStop();
-
- // ATTENTION: This was auto-generated to implement the App Indexing API.
- // See https://g.co/AppIndexing/AndroidStudio for more information.
- Action viewAction = Action.newAction(
- Action.TYPE_VIEW, // TODO: choose an action type.
- "Main Page", // TODO: Define a title for the content shown.
- // TODO: If you have web page content that matches
- // this app activity's content,
- // make sure this auto-generated web page URL is correct.
- // Otherwise, set the URL to null.
- Uri.parse("http://www.example.com/gizmos"),
- // TODO: Make sure this auto-generated app URL is correct.
- Uri.parse("android-app://com.example/http/www.example.com/gizmos")
- );
- AppIndex.AppIndexApi.end(client, viewAction);
- client.disconnect();
- }
-}
-
-
-For more information about the App Indexing API methods, see - Android API for App Indexing. - For information about the action types, see the - Action Class Constant Summary. -
- -If your app isn’t already configured for the Google Play Services App Indexing API, the Code
- Editor also modifies your build.gradle and AndroidManifest.xml files
- to include it. If your app already depends on it but the version is lower than 8.1.0, your app
- is upgraded to version 8.1.0. For more information and to correct any issues, see
- Add Google Play Services
- and Setting Up Google Play Services.
-
Pay attention to the comments, which help you find areas that need work, such as setting the - title and URLs. For more information, see - Add the App Indexing API. -
-To test and debug your App Indexing API code, you can use the following Android Studio - features:
-In addition, you can - preview your APK in the Google Search Console.
- - -When you run your app from Android Studio, you can specify a URL to launch so you can - test it.
- -To launch a URL from Android Studio:
-Or type the URL you want to test, for example, http://example.com/gizmos.
If the link is successful, the app launches in the device or emulator, and displays the app at - the specified activity. Otherwise, an error message appears in the Run window.
-For more information about creating run configurations at the project, default, and module - levels, see - Building and Running from Android Studio. -
- -You can view App Indexing API log messages while the app is running, as described next.
- - -The logcat Monitor can display app indexing log messages to determine if your App Indexing API - code is pushing the correct data to the cloud. For example, you can check the app title and the - URL. The logcat Monitor is part of Android Monitor in Android Studio.
- -To view App Indexing API messages in the logcat Monitor:
-App indexing log messages should appear. If they don’t, check the following items:
-build.gradle file? If so, it might be out-of-date and should be upgraded to
- a higher version. For more information, see the - Google Play Services Download - page and Setting Up Google Play Services. -
-You can use the Android Studio built-in Lint tool to check whether you have valid URLs - defined in the manifest and have implemented the App Indexing API correctly in activities.
- -You can view URL and app indexing warnings and errors in two ways:
-To set default Lint checks for URLs and the App Indexing API:
-For example, the following Lint warning appears for the first setting:
-
To produce a list of Lint checks displayed in the Inspection Results window:
-The scope specifies the files you want to analyze, and the profile specifies the Lint checks - you’d like to perform.
-In the Inspections dialog, you can search for the string "app indexing" -to find the URL and App Indexing API Lint checks. Note that changing Lint settings for a -profile in the Inspections dialog doesn’t change the default settings, as described in -the previous procedure. It does change the settings for profiles displayed in the -Inspections dialog, however.
-The results appear in the Inspection Results window.
- -You can use a Google App Indexing Test to check whether Google can index -a URL by either crawling your app page or using the App Indexing API. -Google can index the URL if your app supports at least one of the following: -
-To perform a Google App Indexing Test:
-Android Studio builds the APK and starts the test. The test can take a few -minutes to complete. The results appear in a new tab in the Code Editor.
-
If the app preview on the right shows the screen that corresponds to the URL -you're testing, then Googlebot can find the URL.
- -The following table lists common errors and warnings you might encounter.
- -| Warning or Error | -Description | -
|---|---|
| Error: Google cannot index this page. | -Your app can't be crawled by Googlebot or using the App Indexing API, - so Google isn't able to index this app. | -
| Warning: The App URL you sent by using the App Indexing API doesn't - match the URL opened. | -When calling the App Indexing API, the URL specified in the app must - match the opened URL. | -
| Warning: Google cannot index this page using the App Indexing API - because the title is empty. | -When calling the App Indexing API, the title shouldn't be empty. | -
| Warning: Google can index this page using Googlebot crawling but - identified blocked resources. | -The app references other resources, and some of them are blocked or
- temporarily unavailable. If these resources aren't critical, it might not
- matter. Check the preview on the right to see whether the content
- displays correctly. To fix this issue, make sure the resources aren't
- blocked by robots.txt. |
-
| Warning: Google cannot index this page using the App Indexing API. | -Your app isn’t using the App Indexing API. We recommended adding App - Indexing API support to your app. | -
The AVD Manager provides a graphical user interface in which you can create -and manage Android Virtual Devices (AVDs), which are required by the -Android Emulator.
- -You can launch the AVD Manager in one of the following ways:
-tools/ directory and execute
- android avd.For more information, see Managing -AVDs with AVD Manager. diff --git a/docs/html/tools/help/bmgr.jd b/docs/html/tools/help/bmgr.jd deleted file mode 100644 index 8823f338a5430b1796c42aa651e44792e7d6c13e..0000000000000000000000000000000000000000 --- a/docs/html/tools/help/bmgr.jd +++ /dev/null @@ -1,190 +0,0 @@ -page.title=bmgr -parent.title=Tools -parent.link=index.html -@jd:body - - - -
bmgr is a shell tool you can use to interact with the Backup Manager
-on Android devices supporting API Level 8 or greater. It provides commands to induce backup
-and restore operations so that you don't need to repeatedly wipe data or take similar
-intrusive steps in order to test your application's backup agent. These commands are
-accessed via the adb shell.
-
-
For information about adding support for backup in your application, read Data Backup, which includes a guide to testing -your application using {@code bmgr}.
- - -Normally, your application must notify the Backup Manager when its data has changed, via {@link
-android.app.backup.BackupManager#dataChanged()}. The Backup Manager will then invoke your
-backup agent's {@link
-android.app.backup.BackupAgent#onBackup(ParcelFileDescriptor,BackupDataOutput,ParcelFileDescriptor)
-onBackup()} implementation at some time in the future. However, instead of calling {@link
-android.app.backup.BackupManager#dataChanged()}, you can invoke a backup request from the command
-line by running the bmgr backup command:
-
-
adb shell bmgr backup <package>- -
<package> is the formal package name of the application you wish to
-schedule for
-backup. When you execute this backup command, your application's backup agent will be invoked to
-perform a backup operation at some time in the future (via your {@link
-android.app.backup.BackupAgent#onBackup(ParcelFileDescriptor,BackupDataOutput,ParcelFileDescriptor)
-onBackup()} method), though there is no guarantee when it will occur. However, you can force all
-pending backup operations to run immediately by using the bmgr run command:
-
-
adb shell bmgr run- -
This causes a backup pass to execute immediately, invoking the backup agents of all applications
-that had previously called {@link android.app.backup.BackupManager#dataChanged()} since the
-last backup operation, plus any applications which had been manually scheduled for
-backup via bmgr backup.
-
-
-
-
Unlike backup operations, which are batched together and run on an occasional basis, restore -operations execute immediately. The Backup Manager currently provides two kinds of restore -operations. The first kind restores an entire device with the data that has been backed up. This -is typically performed only when a device is first provisioned (to replicate settings and other -saved state from the user's previous device) and is an operation that only the system can -perform. The second kind of restore operation restores -a single application to its "active" data set; that is, the application will abandon its current -data and revert to the last-known-good data that is held in the current backup image. You can -invoke this second restore operation with the {@link -android.app.backup.BackupManager#requestRestore(RestoreObserver) requestRestore()} method. The -Backup Manager will then invoke your backup agent's {@link -android.app.backup.BackupAgent#onRestore(BackupDataInput,int,ParcelFileDescriptor) -onRestore()} implementation. - -
While testing your application, you can immediately invoke the restore operation (bypassing the
-{@link android.app.backup.BackupManager#requestRestore(RestoreObserver) requestRestore()} method)
-for your application by using the bmgr restore command:
-
-
adb shell bmgr restore <package>- -
<package> is the formal Java-style package name of the application
-participating in the backup/restore mechanism, which you would like to restore. The Backup
-Manager will immediately instantiate the application's backup agent and invoke it for restore. This
-will happen even if your application is not currently running.
-
-
-
-
-
-
The data for a single application can be erased from the active data set on demand. This is
-very useful while you're developing a backup agent, in case bugs lead you to write corrupt data
-or saved state information. You can wipe an application's data with the bmgr wipe
-command:
-
-
adb shell bmgr wipe <package>- -
<package> is the formal package name of the application whose data
-you wish to
-erase. The next backup operation that the application's agent processes will look as
-though the application had never backed anything up before.
-
-
-
You can see whether the Backup Manager is operational at all with the bmgr
-enabled command:
-
-
adb shell bmgr enabled- -
This might be useful if your application's backup agent is never being invoked for backup, to -verify whether the operating system thinks it should be performing such operations at all.
- -You can also directly disable or enable the Backup Manager with this command: - -
adb shell bmgr enable <boolean>- -
<boolean> is either true or false.
-This is equivalent to disabling or enabling backup in the device's main Settings UI.
Warning! When backup is disabled, the current backup transport
-will explicitly wipe
-the entire active data set from its backend storage. This is so that when a user says
-they do not want their data backed up, the Backup Manager respects that wish. No further
-data will be saved from the device, and no restore operations will be possible, unless the Backup
-Manager is re-enabled (either through Settings or through the above bmgr command).
-
-
-
-
-
diff --git a/docs/html/tools/help/ddms.html b/docs/html/tools/help/ddms.html
deleted file mode 100644
index d885d561dd000f5bb879b354f69954dee3856bec..0000000000000000000000000000000000000000
--- a/docs/html/tools/help/ddms.html
+++ /dev/null
@@ -1,10 +0,0 @@
-
-
You should be redirected. Please click here.
- - \ No newline at end of file diff --git a/docs/html/tools/help/desktop-head-unit.jd b/docs/html/tools/help/desktop-head-unit.jd deleted file mode 100644 index 981979c8e8f55b47bc71bbc2e729e0d2772f1045..0000000000000000000000000000000000000000 --- a/docs/html/tools/help/desktop-head-unit.jd +++ /dev/null @@ -1,439 +0,0 @@ -page.title=Desktop Head Unit -page.tags="auto", "car", "testing","dhu" -@jd:body - - -The Desktop Head Unit (DHU) enables your development machine to emulate an Android Auto -head unit, so you can easily run and test Android Auto apps. The DHU runs on -Windows, Mac, and Linux hosts and replaces previous Android Auto simulators, -such as the Android Media Browser and Messaging -simulators.
- -Note: For other information about testing Auto apps, see the -training lesson -Run and Test Auto Apps.
- - -
- To launch the DHU, run the desktop-head-unit.exe (on Windows)
- or desktop-head-unit (on Mac or Linux) command, as described in
- Connecting
- the DHU to your mobile device.
-
- By default, the DHU emulates the most common form of Android Auto-compatible
- head unit, which uses a touch screen user interface. You can simulate user
- touches by clicking the DHU with a mouse. To emulate head units which use
- a rotary controller for input, you can use the -i controller flag,
- as in this example:
-
$ ./desktop-head-unit -i controller- -
- When the DHU is in rotary-controller mode you can simulate controller - operations by using keyboard shortcuts, as described in DHU commands and key bindings. If the DHU is in rotary - controller mode, it ignores mouse clicks; you must operate Android Auto with - the simulated rotary controller operations. -
- -- DHU commands allow you to test your app with Android Auto features, such as - playing voice input or switching between night and day display mode. You can issue commands to - the DHU by running commands from the terminal window where you launched DHU. - You can also issue commands by selecting the DHU window and - using keyboard shortcuts. The DHU commands - and key bindings for all controls are listed in DHU - commands and key bindings. -
- - -- Android Auto supports different color schemes for day and night. You should test your app in both - day and night mode. You can switch between night and day mode in either of the - following ways: -
- -daynight in the terminal where you launched the DHU.
- The DHU supports using a microphone for voice input. You can also instruct the DHU to treat -a pre-recorded voice track as input, as if the DHU had heard the track through the microphone.
- -To use a pre-recorded sound file as input, enter this command:
--$ mic play <sound_file_path>/<sound_file>.wav -- -
For your convenience, we have provided the following sound files for common
-voice commands. These sound files are installed in the
-<sdk>/extras/google/auto/voice/ directory.
exitnav.wav
- navgoogle.wav
- navsoh.wav
- nextturn.wav
- showalternateroute.wav
- howlong.wav
- navhome.wav
- navwork.wav
- pause.wav
- showtraffic.wav
- The DHU supports the following commands.
- -Table 1. Commands and key bindings
-| Category | -Command | -Subcommand | -Argument(s) | -Keyboard Shortcut(s) | -Description | -
|---|---|---|---|---|---|
| System | -help | -- | [command] | -- | Shows the full command set. Specifying a command name (for example, help day)
- causes the system to show help for that command. |
-
| quit | -- | - | Alt+q | -Quits the head unit. | -|
| sleep | -- | [seconds] | -- | Sleeps for one second. Specifying an argument (for example, sleep 30) causes the
-system to sleep the specified number of seconds. This command
-is useful if you are writing scripts for the DHU. (You can run a script by using I/O redirection
-from the command line: ./desktop-head-unit < script.txt loads commands from the
-file script.txt.) |
-|
| screenshot | -- | filename.png | -- | Saves a screenshot to filename.png. |
-|
| Microphone | -mic | -begin | -- | m | -Activates the microphone (equivalent to clicking the steering wheel's microphone button) and -waits for input from the computer microphone. | -
| play | -filename.wav | -- | Causes the DHU to treat filename.wav as voice input, as if it had heard that sound
- through the microphone. You do not hear the sound file being played, but you do hear
- the response from Android Auto. |
-||
| repeat | -- | - | Repeats the last mic play command, as if you had called mic play
- again with the same sound file parameter. |
-||
| Input | -dpad | -up down left right |
-- | Arrow keys | -Simulates moving the rotary controller. | -
| soft left soft right |
-- | Shift+Arrow keys | -Simulates pressing the side buttons available on some rotary controllers. | -||
| click | -- | Return | -Simulates pressing the rotary controller. | -||
| back | -- | Backspace | -Simulates pressing the back button available below some rotary - controllers. | -||
| rotate left rotate right |
-- | 1 2 |
-Simulates rotating the rotary controller left (counter-clockwise) or right (clockwise). | -||
| flick left flick right |
-- | Shift+1 Shift+2 |
-Simulates a fast spin of the rotary controller to the left (counter-clockwise) or right - (clockwise). | -||
| tap | -- | x y | -- | Simulates a touch event at the specified coordinates. For example, tap 50 100 |
-|
| Day/Night | -day | -- | - | Shift+n | -Activates day mode (high brightness, full color). | -
| night | -- | - | Ctrl+n | -Activates night mode (low brightness, high contrast). | -|
| daynight | -- | - | n | -Toggles current day/night mode. | -
Important: Use of the Android Media Browser and Messaging -Simulators for testing Android Auto apps is deprecated. Instead, we recommend using the -Desktop Head Unit, which enables your development machine to act as if it were an Android Auto head -unit.
- -To get the simulators, open the -SDK Manager and download -them from Extras > Android Auto API Simulators.
- -Before you begin testing, compile your app in your development environment. -Install your app and the Android simulator for the features you want to test -(that is, audio or messaging) on a physical or virtual device running Android -5.0 (API level 21) or higher. To check the version of Android on the device, go -to Settings > About phone (or About tablet) -> Android Version.
- -To run and test audio apps:
- -To run and test messaging apps:
- -dmtracedump is a tool that gives you an alternate way of generating
- graphical call-stack diagrams from trace log files (instead of using Traceview).
This document is a reference to the available command line options. For more information on generating trace - logs, see Profiling with - Traceview and dmtracedump.
- -The usage for dmtracedump is:
-dmtracedump [-ho] [-s sortable] [-d trace-base-name] [-g outfile] <trace-base-name> -- -
The tool then loads trace log data from <trace-base-name>.data and
- <trace-base-name>.key. The table below lists the options for dmtracedump.
| Option | - -Description | -
|---|---|
-d <trace-base-name> |
-
- Diff with this trace name | -
-g <outfile> |
-
- Generate output to <outfile> | -
-h |
-
- Turn on HTML output | -
-o |
-
- Dump the trace file instead of profiling | -
-d <trace-base-name> |
-
- URL base to the location of the sortable javascript file | -
-t <percent> |
-
- Minimum threshold for including child nodes in the graph (child's inclusive time as a - percentage of parent inclusive time). If this option is not used, the default threshold is - 20%. | -
The Draw 9-patch tool is a WYSIWYG editor that allows you to create bitmap images that -automatically resize to accommodate the contents of the view and the size of the screen. Selected -parts of the image are scaled horizontally or vertically based indicators drawn within the image.
-For an introduction to NinePatch graphics and how they work, please read -the section about NinePatch Drawables in the -Canvas and Drawables -document.
- -
-
-Here's a quick guide to create a NinePatch graphic using the Draw 9-patch tool. -You'll need the PNG image with which you'd like to create a NinePatch image.
- -draw9patch command from your SDK
- sdk/tools directory to launch the Draw 9-patch tool.
- The left pane is your drawing area, in which you can edit the lines for the - stretchable patches and content area. The right - pane is the preview area, where you can preview your graphic when stretched.
-Your image will be saved with the .9.png file name.
To make sure that your NinePatch graphics scale down properly, verify that any - stretchable regions are at least 2x2 pixels in size. - Otherwise, they may disappear when scaled down. Also, provide one pixel of extra safe space in - the graphics before and after stretchable regions to avoid interpolation during scaling that may - cause the color at the boundaries to change.
- -Note: A normal PNG file (*.png) will be
- loaded with an empty one-pixel border added around the image, in which you can draw
- the stretchable patches and content area.
- A previously saved NinePatch file (*.9.png) will be loaded as-is,
- with no drawing area added, because it already exists.
-
-Optional controls include:
-The Android SDK includes a mobile device emulator — a virtual mobile device -that runs on your computer. The emulator lets you develop and test -Android applications without using a physical device.
- -This page describes command line features that you can use with the -Android Emulator. -For information about using the Android Emulator UI, see -Using the Android Emulator. -
- - -During development and testing of your application, you install and run your -application in the Android Emulator. You can launch the emulator as a standalone -application from a command line, or you can run it from within your Android Studio -development environment. In either case, you specify the AVD configuration to -load and any startup options you want to use, as described in this document. -
- -You can run your application on a single instance of the emulator or, -depending on your needs, you can start multiple emulator instances and run your -application in more than one emulated device. You can use the emulator's -built-in commands to simulate GSM phone calling or SMS between emulator -instances, and you can set up network redirection that allows emulators to send -data to one another. For more information, see Telephony -Emulation, SMS Emulation, and -Emulator Networking
- -To start an instance of the emulator from the command line, navigate to the
-tools/ folder of the SDK. Enter emulator command
-like this:
emulator -avd <avd_name> [<options>]- -
This initializes the emulator, loads an AVD configuration and displays the emulator -window. For more information about command line options for the emulator, see the -Android Emulator tool reference.
- -Note: You can run multiple -instances of the emulator concurrently, each with its own AVD configuration and -storage area for user data, SD card, and so on.
- -When you run your app from Android Studio, it installs and launches the -app on your connected device or emulator (launching the emulator, if necessary). -You can specify emulator startup options in the Run/Debug -dialog, in the Target tab. When the emulator is running, you can issue -console commands as described later in this document.
- -If you are not working in Android Studio, see Installing Applications -on the Emulator for information about how to install your application.
- -To stop an emulator instance, just close the emulator's window.
- -For a reference of the emulator's startup commands and keyboard mapping, see -the Android Emulator tool -reference.
- - -If you don't have access to Android Studio, you can install your application on the
-emulator using the adb utility. Before
-installing the application, you need to build and package it into an .apk as described
-in Building and
-Running Apps. Once the application is installed, you can start the emulator from the command
-line as described previously, using any startup options necessary.
-When the emulator is running, you can also connect to the emulator instance's
-console to issue commands as needed.
As you update your code, you periodically package and install it on the emulator.
-The emulator preserves the application and its state data across restarts,
-in a user-data disk partition. To ensure that the application runs properly
-as you update it, you may need to delete the emulator's user-data partition.
-To do so, start the emulator with the -wipe-data option.
-For more information about the user-data partition and other emulator storage,
-see Working with Emulator Disk Images.
The emulator supports a variety of options that you can specify -when launching the emulator, to control its appearance or behavior. -Here's the command-line syntax of the options available to the {@code emulator} program:
- -emulator -avd <avd_name> [-<option> [<value>]] ... [-<qemu args>]- -
Table 2. Emulator command line parameters
-| Category | -Option | -Description | -Comments | -
|---|---|---|---|
| AVD | --avd <avd_name> or - @<avd_name> |
- Required. Specifies the AVD to load for this emulator - instance. | -You must create an AVD configuration before launching the emulator. For - information, see Managing - AVDs with AVD Manager. | -
| Disk Images | --cache <filepath> |
- Use <filepath> as the working cache partition image. | -An absolute or relative path to the current working directory.
- If no cache file is specified, the emulator's default behavior is to use a temporary file instead.
- For more information on disk images, use |
-data <filepath> |
- Use {@code <filepath>} as the working user-data disk image. | -Optionally, you can specify a path relative to the current working directory.
- If -data is not used, the emulator looks for a file named {@code userdata-qemu.img}
- in the storage area of the AVD being used (see -avd).
- | |
-initdata <filepath> |
- When resetting the user-data image (through -wipe-data), copy the contents
- of this file to the new user-data disk image. By default, the emulator copies the <system>/userdata.img. |
- Optionally, you can specify a path relative to the current working directory. See also -wipe-data.
- For more information on disk images, use |
-|
-nocache |
- Start the emulator without a cache partition. | -See also -cache <file>. |
-|
-ramdisk <filepath> |
- Use <filepath> as the ramdisk image. | -Default value is <system>/ramdisk.img.
- Optionally, you can specify a path relative to the current working directory.
- For more information on disk images, use |
-|
-sdcard <filepath> |
- Use <file> as the SD card image. | -Default value is <system>/sdcard.img.
- Optionally, you can specify a path relative to the current working directory. For more information on disk images, use |
-|
-wipe-data |
- Reset the current user-data disk image (that is, the file specified by -datadir and
- -data, or the default file). The emulator deletes all data from the user data image file,
- then copies the contents of the file at -inidata data to the image file before starting.
- |
- See also -initdata.
- For more information on disk images, use |
-|
| Debug | --debug <tags> |
- Enable/disable debug messages for the specified debug tags. | -<tags> is a space/comma/column-separated list of debug component names.
- Use -help-debug-tags to print a list of debug component names that you can use. |
-
-debug-<tag> |
- Enable/disable debug messages for the specified debug tag. | -Use -help-debug-tags to print a list of debug component names that you can use in <tag>. |
-|
-debug-no-<tag> |
- Disable debug messages for the specified debug tag. | -||
-logcat <logtags> |
- Enable logcat output with given tags. | -If the environment variable ANDROID_LOG_TAGS is defined and not - empty, its value will be used to enable logcat output by default. | -|
-shell |
- Create a root shell console on the current terminal. | -You can use this command even if the adb daemon in the emulated system is broken. - Pressing Ctrl-c from the shell stops the emulator instead of the shell. | -|
-shell-serial <device> |
- Enable the root shell (as in -shell and specify the QEMU character
- device to use for communication with the shell. |
- <device> must be a QEMU device type. See the documentation for '-serial dev' at
- http://wiki.qemu.org/download/qemu-doc.html
- for a list of device types.
-
- Here are some examples: -
|
-|
-show-kernel <name> |
- Display kernel messages. | -- | |
-trace <name> |
- Enable code profiling (press F9 to start), written to a specified file. | -- | |
-verbose |
- Enable verbose output. | -Equivalent to -debug-init.
-You can define the default verbose output options used by emulator instances in the Android environment variable
-ANDROID_VERBOSE. Define the options you want to use in a comma-delimited list, specifying only the stem of each option:
- Here's an example showing ANDROID_VERBOSE defined with the
For more information about debug tags, use |
-|
| Media | --audio <backend> |
- Use the specified audio backend. | -- |
-audio-in <backend> |
- Use the specified audio-input backend. | -- | |
-audio-out <backend> |
- Use the specified audio-output backend. | -- | |
-noaudio |
- Disable audio support in the current emulator instance. | -- | |
-radio <device> |
- Redirect radio modem interface to a host character device. | -||
-useaudio |
- Enable audio support in the current emulator instance. | -Enabled by default. | -|
| Network | --dns-server <servers> |
- Use the specified DNS server(s). | -The value of <servers> must be a comma-separated list of up to 4 DNS server names or
- IP addresses. |
-
-http-proxy <proxy> |
- Make all TCP connections through a specified HTTP/HTTPS proxy | -The value of <proxy> can be one of the following:- http://<server>:<port>- http://<username>:<password>@<server>:<port>
- The |
-|
-netdelay <delay> |
- Set network latency emulation to <delay>. | -Default value is none. See the table in
- Network Delay Emulation
- for supported <delay> values. |
-|
-netfast |
- Shortcut for -netspeed full -netdelay none |
- ||
-netspeed <speed> |
- Set network speed emulation to <speed>. | -Default value is full. See the table in
- Network Speed Emulation for
- supported <speed> values. |
-|
-port <port> |
- Set the console port number for this emulator instance to <port>. |
- The console port number must be an even integer between 5554 and 5584, inclusive. <port>+1
- must also be free and will be reserved for ADB. |
-|
-report-console <socket> |
- Report the assigned console port for this emulator instance to a remote third party - before starting the emulation. | -<socket> must use one of these formats:
-
-
Use |
-|
| System | --cpu-delay <delay> |
- Slow down emulated CPU speed by <delay> | -Supported values for <delay> are integers between 0 and 1000.
-
- Note that the <delay> does not correlate to clock speed or other absolute metrics -— it simply represents an abstract, relative delay factor applied non-deterministically -in the emulator. Effective performance does not always -scale in direct relationship with <delay> values. - |
-
-gps <device> |
- Redirect NMEA GPS to character device. | -Use this command to emulate an NMEA-compatible GPS unit connected to
- an external character device or socket. The format of <device> must be QEMU-specific
- serial device specification. See the documentation for 'serial -dev' at
- http://wiki.qemu.org/download/qemu-doc.html.
- |
-|
-nojni |
- Disable JNI checks in the Dalvik runtime. | ||
-qemu |
- Pass arguments to the qemu emulator software. | -Important: When using this option, make sure it is the - last option specified, since all options after it are interpretted as qemu-specific - options. | |
-qemu -enable-kvm |
- Enable KVM acceleration of the emulator virtual machine. | -This option is only effective when your system is set up to use
- KVM-based VM acceleration.
- You can optionally specify a memory size ({@code -m <size>}) for the VM, which should match
- your emulator's memory size:
- {@code -qemu -m 512 -enable-kvm} - {@code -qemu -m 1024 -enable-kvm} - | |
-qemu -h |
- Display qemu help. | -||
-gpu on |
- Turn on graphics acceleration for the emulator. | -This option is only available for emulators using a system image with API Level 15, revision 3 - and higher. For more information, see - Using the Android - Emulator. | |
-radio <device> |
- Redirect radio mode to the specified character device. | -The format of <device> must be QEMU-specific
- serial device specification. See the documentation for 'serial -dev' at
-http://wiki.qemu.org/download/qemu-doc.html.
- |
-|
-timezone <timezone> |
- Set the timezone for the emulated device to <timezone>, instead of the host's timezone. | -<timezone> must be specified in zoneinfo format. For example:
-"America/Los_Angeles" |
-|
-version |
- Display the emulator's version number. | -- | |
| UI | --dpi-device <dpi> |
- Scale the resolution of the emulator to match the screen size - of a physical device. | -The default value is 165. See also -scale. |
-
-no-boot-anim |
- Disable the boot animation during emulator startup. | -Disabling the boot animation can speed the startup time for the emulator. | -|
-no-window |
- Disable the emulator's graphical window display. | -- | |
-scale <scale> |
- Scale the emulator window. | -<scale> is a number between 0.1 and 3 that represents the desired scaling factor. You can
- also specify scale as a DPI value if you add the suffix "dpi" to the scale value. A value of "auto"
- tells the emulator to select the best window size. |
-|
-raw-keys |
- Disable Unicode keyboard reverse-mapping. | -||
-noskin |
- Don't use any emulator skin. | -||
-keyset <file> |
- Use the specified keyset file instead of the default. | -The keyset file defines the list of key bindings between the emulator and the host keyboard.
- For more information, use -help-keyset to print information about this topic.
- |
-|
-onion <image> |
- Use overlay image over screen. | -No support for JPEG. Only PNG is supported. | |
-onion-alpha <percent> |
- Specify onion skin translucency value (as percent). - | Default is 50. | -|
-onion-rotation <position> |
- Specify onion skin rotation. - | <position> must be one of the values 0, 1, 2, 3. |
-|
-skin <skinID> |
- This emulator option is deprecated. | -Please set skin options using AVDs, rather than by using this emulator -option. Using this option may yield unexpected and in some cases misleading -results, since the density with which to render the skin may not be defined. -AVDs let you associate each skin with a default density and override the default -as needed. For more information, see Managing Virtual Devices -with AVD Manager. - | -|
-skindir <dir> |
- This emulator option is deprecated. | -See comments for -skin, above. |
-|
| Help | --help |
- Print a list of all emulator options. | -- |
-help-all |
- Print help for all startup options. | -- | |
-help-<option> |
- Print help for a specific startup option. | -- | |
-help-debug-tags |
- Print a list of all tags for -debug <tags>. |
- - | |
-help-disk-images |
- Print help for using emulator disk images. | -- | |
-help-environment |
- Print help for emulator environment variables. | -s - | |
-help-keys |
- Print the current mapping of keys. | -- | |
-help-keyset-file |
- Print help for defining a custom key mappings file. | -- | |
-help-virtual-device |
- Print help for Android Virtual Device usage. | -- |
To make the Android emulator run faster and be more responsive, you can configure it to -take advantage of hardware acceleration, using a combination of configuration options, specific -Android system images and hardware drivers.
- - -Caution: As of SDK Tools Revision 17, the graphics -acceleration feature for the emulator is experimental; be alert for incompatibilities and -errors when using this feature.
- -Graphics acceleration for the emulator takes advantage of your development computer's graphics -hardware, specifically its graphics processing unit (GPU), to make screen drawing faster. To use -the graphics acceleration feature, you must have the following versions of the Android development -tools installed:
- -Use the Android SDK -Manager to install these components:
- -Note: Not all applications are compatible with graphics hardware -acceleration. In particular, the Browser application and applications using the {@link -android.webkit.WebView} component are not compatible with graphics acceleration.
- -To configure an AVD to use graphics acceleration:
- -Note: You can also enable graphics acceleration when you -start an emulator using command line options as describe in the next section.
-Caution: Do not select the Snapshot: Enabled -option. Snapshots are not supported for emulators with graphics acceleration enabled.
-If you set GPU emulation to Yes for your AVD, then graphics -acceleration is automatically enabled when you run it. If you did not enable GPU -emulation when you created the AVD, you can still enable it at runtime.
- -To enable graphics acceleration at runtime for an AVD:
- -emulator -avd <avd_name> -gpu on-
Note: You must specify an AVD configuration that uses -Android 4.0.3 (API Level 15, revision 3) or higher system image target. Graphics acceleration is not -available for earlier system images.
-Caution: As of SDK Tools Revision 17, the virtual machine -acceleration feature for the emulator is experimental; be alert for incompatibilities and errors -when using this feature.
- -Many modern CPUs provide extensions for running virtual machines (VMs) more efficiently. Taking -advantage of these extensions with the Android emulator requires some additional configuration of -your development system, but can significantly improve the execution speed. Before attempting to use -this type of acceleration, you should first determine if your development system’s CPU supports one -of the following virtualization extensions technologies:
- -The specifications from the manufacturer of your CPU should indicate if it supports -virtualization extensions. If your CPU does not support one of these virtualization technologies, -then you cannot use virtual machine acceleration.
- -Note: Virtualization extensions are typically enabled through -your computer's BIOS and are frequently turned off by default. Check the documentation for your -system's motherboard to find out how to enable virtualization extensions.
- -Once you have determined that your CPU supports virtualization extensions, make sure you can work -within these additional requirements of running an emulator inside an accelerated virtual -machine:
- -To use virtual machine acceleration with the emulator, you need the following version of Android -development tools. Use the Android SDK -Manager to install these components:
- -If your development environment meets all of the requirements for running a VM-accelerated -emulator, you can use the AVD Manager to create an x86-based AVD configuration:
- -Tip: System images are listed under each API Level in the SDK - Manager. An x86 system image may not be available for all API levels.
-Virtual machine acceleration for Windows requires the installation of the Intel Hardware -Accelerated Execution Manager (Intel HAXM). The software requires an Intel CPU with -Virtualization Technology (VT) support and one of the following operating systems:
- -To install the virtualization driver:
- -sc query intelhaxm-
You should see a status message including the following information:
--SERVICE_NAME: intelhaxm - ... - STATE : 4 RUNNING - ... --
To run an x86-based emulator with VM acceleration:
-emulator -avd <avd_name>-
Note: You must provide an x86-based AVD configuration -name, otherwise VM acceleration will not be enabled.
-You can adjust the amount of memory available to the Intel HAXM kernel extension by re-running -its installer.
- -You can stop using the virtualization driver by uninstalling it. Re-run the installer or use -the Control Panel to remove the software.
- - -Virtual machine acceleration on a Mac requires the installation of the Intel Hardware Accelerated -Execution Manager (Intel HAXM) kernel extension to allow the Android emulator to make use of CPU -virtualization extensions. The kernel extension is compatible with Mac OS X Snow Leopard (version -10.6.0) and higher.
- -To install the Intel HAXM kernel extension:
- -kextstat | grep intel-
You should see a status message containing the following extension name, indicating that the - kernel extension is loaded:
-com.intel.kext.intelhaxm-
To run an x86-based emulator with VM acceleration:
-emulator -avd <avd_name>-
Note: You must provide an x86-based AVD configuration -name, otherwise VM acceleration will not be enabled.
-You can adjust the amount of memory available to the Intel HAXM kernel extension by re-running -the installer.
- -You can stop using the virtualization kernel driver by uninstalling it. Before removing it, shut -down any running x86 emulators. To unload the virtualization kernel driver, run the following -command in a terminal window:
- -sudo /System/Library/Extensions/intelhaxm.kext/Contents/Resources/uninstall.sh- -
Linux-based systems support virtual machine acceleration through the KVM software package. Follow -instructions for installing KVM on your -Linux system, and verify that KVM is enabled. In addition to following the installation -instructions, be aware of these configuration requirements:
- -To run an x86-based emulator with VM acceleration:
- -emulator -avd <avd_name> -qemu -m 512 -enable-kvm-
Note: You must provide an x86-based AVD configuration -name, otherwise VM acceleration will not be enabled.
--qemu -m 512 -enable-kvm-
Important: When using the {@code -qemu} command line option, make sure -it is the last parameter in your command. All subsequent options are interpreted as qemu-specific -parameters.
- - -You can create a disk image and then load it to the emulator at startup, to -simulate the presence of a user's SD card in the device. To do this, you can specify -an SD card image when you create an AVD, or you can use the mksdcard utility included -in the SDK.
- -The following sections describe how to create an SD card disk image, how to copy -files to it, and how to load it in the emulator at startup.
- -Note that you can only load a disk image at emulator startup. Similarly, you -can not remove a simulated SD card from a running emulator. However, you can -browse, send files to, and copy/remove files from a simulated SD card either -with adb or the emulator.
- -The emulator supports emulated SDHC cards, so you can create an SD card image -of any size up to 128 gigabytes.
- - -There are several ways of creating an SD card image. The easiest way is to use the
-AVD Manager to create a new SD card by specifying a size when you create an AVD.
-You can also use the {@code android} command line tool when creating an AVD. Just add the
--c option to your command:
android create avd -n <avd_name> -t <targetID> -c <size>[K|M]- -
The -c option can also be used to to specify a path to an SD card
-image for the new AVD. For more information, see Managing Virtual Devices
-from the Command Line.
-
You can also use the mksdcard tool, included in the SDK, to create a FAT32 disk -image that you can load in the emulator at startup. You can access mksdcard in -the tools/ directory of the SDK and create a disk image like this:
- -mksdcard <size> <file>- -
For example:
- -mksdcard 1024M sdcard1.iso- -
For more information, see mksdcard.
Once you have created the disk image, you can copy files to it prior to -loading it in the emulator. To copy files, you can mount the image as a loop -device and then copy the files to it, or you can use a utility such as {@code mtools} to -copy the files directly to the image. The {@code mtools} package is available for Linux, -Mac, and Windows.
- -Alternatively, you can use the {@code adb push} command to move files onto an SD card image -while it is loaded in an emulator. For more information see the {@code adb push} documentation.
- -By default, the emulator loads the SD card image that is stored with the active
-AVD (see the -avd startup option).
Alternatively, you can start the emulator with the
--sdcard flag and specify the name and path of your image (relative
-to the current working directory):
emulator -sdcard <filepath>- - -
The emulator uses mountable disk images stored on your development machine to -simulate flash (or similar) partitions on an actual device. For example, it uses a -disk image containing an emulator-specific kernel, the Android system, a -ramdisk image, and writeable images for user data and simulated SD card.
- -To run properly, the emulator requires access to a specific set of disk image -files. By default, the Emulator always looks for the disk images in the -private storage area of the AVD in use. If no images exist there when -the Emulator is launched, it creates the images in the AVD directory based on -default versions stored in the SDK.
- -Note: The default storage location for
-AVDs is in ~/.android/avd on OS X and Linux, C:\Documents and
-Settings\<user>\.android\ on Windows XP, and
-C:\Users\<user>\.android\
-on Windows Vista.
To let you use alternate or custom versions of the image files, the emulator -provides startup options that override the default locations and filenames of -the image files. When you use one of these options, the emulator searches for the image -file under the image name or location that you specify; if it can not locate the -image, it reverts to using the default names and location.
- -The emulator uses three types of image files: default image files, runtime -image files, and temporary image files. The sections below describe how to -override the location/name of each type of file.
- -When the emulator launches, but does not find an existing user data image in -the active AVD's storage area, it creates a new one from a default version -included in the SDK. The default user data image is read-only. The image -files are read-only.
- -The emulator provides the -system <dir> startup option to
-let you override the location where the emulator looks for the default
-user data image.
The emulator also provides a startup option that lets you override the name
-of the default user data image, as described in the following table. When you use the
-option, the emulator looks in the default directory, or in a custom location
-(if you specified -system <dir>).
| Name | -Description | -Comments | -
|---|---|---|
userdata.img |
- The initial user-data disk image | -Override using -initdata <file>. Also see
--data <file>, below. |
-
At runtime, the emulator reads and writes data to two disk images: a -user-data image and (optionally) an SD card image. These images emulate the user-data -partition and removable storage media on actual device.
- -The emulator provides a default user-data disk image. At startup, the emulator -creates the default image as a copy of the system user-data image (user-data.img), -described above. The emulator stores the new image with the files of the active AVD.
- - - -The emulator provides startup options to let you override the actual names and storage -locations of the runtime images to load, as described in the following table. When you use one -of these options, the emulator looks for the specified file(s) in the current working directory, -in the AVD directory, or in a custom location (if you specified a path with the filename).
- -| Name | -Description | -Comments | -
|---|---|---|
userdata-qemu.img |
- An image to which the emulator writes runtime user-data for a unique user. | -Override using -data <filepath>, where <filepath> is the
-path the image, relative to the current working directory. If you supply a filename only,
-the emulator looks for the file in the current working directory. If the file at <filepath> does
-not exist, the emulator creates an image from the default userdata.img, stores it under the name you
-specified, and persists user data to it at shutdown. |
-
sdcard.img |
- An image representing an SD card inserted into the emulated device. | -Override using -sdcard <filepath>, where <filepath> is the
-path the image, relative to the current working directory. If you supply a filename only,
-the emulator looks for the file in the current working directory. |
-
Each emulator instance uses a writeable user-data image to store user- and -session-specific data. For example, it uses the image to store a unique user's -installed application data, settings, databases, and files.
- -At startup, the emulator attempts to load a user-data image stored during -a previous session. It looks for the file in the current working directory, -in the AVD directory described in a previous section and at the custom location/name -that you specified at startup.
- --data startup option.Note: Because of the AVD configurations used in the emulator,
-each emulator instance gets its own dedicated storage. There is no longer a need
-to use the -d option to specify an instance-specific storage area.
Optionally, you can create a writeable disk image that the emulator can use -to simulate removeable storage in an actual device. For information about how to create an -emulated SD card and load it in the emulator, see SD Card Emulation
- -You can also use the android tool to automatically create an SD Card image -for you, when creating an AVD. For more information, see Managing Virtual Devices with AVD -Manager. - - -
The emulator creates two writeable images at startup that it deletes at -device power-off. The images are:
- -/cache partition imageThe emulator does not permit renaming the temporary system image or -persisting it at device power-off.
- -The /cache partition image is initially empty, and is used by
-the browser to cache downloaded web pages and images. The emulator provides an
--cache <file>, which specifies the name of the file in which
-to persist the /cache image at device power-off. If <file>
- does not exist, the emulator creates it as an empty file.
You can also disable the use of the cache partition by specifying the
--nocache option at startup.
The emulator provides versatile networking capabilities that you can use to -set up complex modeling and testing environments for your application. The -sections below introduce the emulator's network architecture and capabilities. -
- -Each instance of the emulator runs behind a virtual router/firewall service -that isolates it from your development machine's network interfaces and settings -and from the internet. An emulated device can not see your development machine -or other emulator instances on the network. Instead, it sees only that it is -connected through Ethernet to a router/firewall.
- -The virtual router for each instance manages the 10.0.2/24 network address -space — all addresses managed by the router are in the form of -10.0.2.<xx>, where <xx> is a number. Addresses within this space are -pre-allocated by the emulator/router as follows:
- -| Network Address | -Description | -
|---|---|
| 10.0.2.1 | -Router/gateway address | -
| 10.0.2.2 | -Special alias to your host loopback interface (i.e., 127.0.0.1 on your -development machine) | -
| 10.0.2.3 | -First DNS server | -
| 10.0.2.4 / 10.0.2.5 / 10.0.2.6 | -Optional second, third and fourth DNS server (if any) | -
| 10.0.2.15 | -The emulated device's own network/ethernet interface | -
| 127.0.0.1 | -The emulated device's own loopback interface | -
Note that the same address assignments are used by all running emulator -instances. That means that if you have two instances running concurrently on -your machine, each will have its own router and, behind that, each will have an -IP address of 10.0.2.15. The instances are isolated by a router and can -not see each other on the same network. For information about how to -let emulator instances communicate over TCP/UDP, see Connecting Emulator Instances.
- -Also note that the address 127.0.0.1 on your development machine corresponds -to the emulator's own loopback interface. If you want to access services running -on your development machine's loopback interface (a.k.a. 127.0.0.1 on your -machine), you should use the special address 10.0.2.2 instead.
- -Finally, note that each emulated device's pre-allocated addresses are -specific to the Android emulator and will probably be very different on real -devices (which are also very likely to be NAT-ed, i.e., behind a -router/firewall)
- - -Android applications running in an emulator can connect to the network available on your -workstation. However, they connect through the emulator, not directly to hardware, and the emulator -acts like a normal application on your workstation. This means that the emulator, and thus your -Android applications, are subject to some limitations:
- -The emulator's virtual router should be able to handle all outbound TCP and -UDP connections/messages on behalf of the emulated device, provided your -development machine's network environment allows it to do so. There are no -built-in limitations on port numbers or ranges except the one imposed by your -host operating system and network.
- -Depending on the environment, the emulator may not be able to support other -protocols (such as ICMP, used for "ping") might not be supported. Currently, the -emulator does not support IGMP or multicast.
- -To communicate with an emulator instance behind its virtual router, you need -to set up network redirection on the virtual router. Clients can then connect -to a specified guest port on the router, while the router directs traffic -to/from that port to the emulated device's host port.
- -To set up the network redirection, you create a mapping of host and guest -ports/addresses on the emulator instance. There are two ways to set up -network redirection: using emulator console commands and using the ADB tool, as -described below.
- - -Each emulator instance provides a control console the you can connect to, to
-issue commands that are specific to that instance. You can use the
-redir console command to set up redirection as needed for an
-emulator instance.
First, determine the console port number for the target emulator instance. -For example, the console port number for the first emulator instance launched is -5554. Next, connect to the console of the target emulator instance, specifying -its console port number, as follows:
- -telnet localhost 5554Once connected, use the redir command to work with redirection.
-To add a redirection, use:
add <protocol>:<host-port>:<guest-port>
-where <protocol> is either tcp or udp,
-and <host-port> and <guest-port> sets the
-mapping between your own machine and the emulated system, respectively.
For example, the following command sets up a redirection that handles all -incoming TCP connections to your host (development) machine on 127.0.0.1:5000 -and will pass them through to the emulated system's 10.0.2.15:6000.:
- -redir add tcp:5000:6000- -
To delete a redirection, you can use the redir del command. To
-list all redirection for a specific instance, you can use redir
-list. For more information about these and other console commands, see
-Using the Emulator Console.
Note that port numbers are restricted by your local environment. this typically
-means that you cannot use host port numbers under 1024 without special
-administrator privileges. Also, you won't be able to set up a redirection for a
-host port that is already in use by another process on your machine. In that
-case, redir generates an error message to that effect.
The Android Debug Bridge (ADB) tool provides port forwarding, an alternate -way for you to set up network redirection. For more information, see Forwarding Ports in the ADB -documentation.
- -Note that ADB does not currently offer any way to remove a redirection, -except by killing the ADB server.
- - -At startup, the emulator reads the list of DNS servers that your system is -currently using. It then stores the IP addresses of up to four servers on this -list and sets up aliases to them on the emulated addresses 10.0.2.3, 10.0.2.4, -10.0.2.5 and 10.0.2.6 as needed.
- -On Linux and OS X, the emulator obtains the DNS server addresses by parsing
-the file /etc/resolv.conf. On Windows, the emulator obtains the
-addresses by calling the GetNetworkParams() API. Note that this
-usually means that the emulator ignores the content of your "hosts" file
-(/etc/hosts on Linux/OS X, %WINDOWS%/system32/HOSTS
- on Windows).
When starting the emulator at the command line, you can also use the
--dns-server <serverList> option to manually specify the
-addresses of DNS servers to use, where <serverList> is a comma-separated
-list of server names or IP addresses. You might find this option useful if you
-encounter DNS resolution problems in the emulated network (for example, an
-"Unknown Host error" message that appears when using the web browser).
If your emulator must access the Internet through a proxy server, you can use
-the -http-proxy <proxy> option when starting the emulator, to
-set up the appropriate redirection. In this case, you specify proxy information
-in <proxy> in one of these formats:
http://<machineName>:<port>- -
or
- -http://<username>:<password>@<machineName>:<port>- -
The -http-proxy option forces the emulator to use the specified
-HTTP/HTTPS proxy for all outgoing TCP connections. Redirection for UDP is not
-currently supported.
Alternatively, you can define the environment variable
-http_proxy to the value you want to use for
-<proxy>. In this case, you do not need to specify a value for
-<proxy> in the -http-proxy command — the
-emulator checks the value of the http_proxy environment variable at
-startup and uses its value automatically, if defined.
You can use the -verbose-proxy option to diagnose proxy
-connection problems.
To allow one emulator instance to communicate with another, you must set up -the necessary network redirection as illustrated below.
- -Assume that your environment is
- -and you want to run a server on B, to which C will connect, here is how you -could set it up:
- -10.0.2.15:<serverPort>A:localhost:<localPort> to
-B:10.0.2.15:<serverPort>10.0.2.2:<localPort>For example, if you wanted to run an HTTP server, you can select
-<serverPort> as 80 and <localPort> as
-8080:
redir add tcp:8080:80The emulator automatically forwards simulated voice calls and SMS messages from one instance to -another. To send a voice call or SMS, use the dialer application or SMS application, respectively, -from one of the emulators.
- -To initiate a simulated voice call to another emulator instance:
-To send an SMS message to another emulator instance, launch the SMS application (if available). Specify the console port number of the target emulator instance as as the SMS address, enter the message text, and send the message. The message is delivered to the target emulator instance.
- -You can also connect to an emulator instance's console to simulate an incoming voice call or SMS. For more information, see Telephony Emulation and SMS Emulation. - - -
Each running emulator instance provides a console that lets you query and control the emulated -device environment. For example, you can use the console to manage port redirection, network -characteristics, and telephony events while your application is running on the emulator. To -access the console and enter commands, use telnet to connect to the console's port number.
- -To connect to the console of any running emulator instance at any time, use this command:
- -telnet localhost <console-port>- -
An emulator instance occupies a pair of adjacent ports: a console port and an {@code adb} port. -The port numbers differ by 1, with the {@code adb} port having the higher port number. The console -of the first emulator instance running on a given machine uses console port 5554 and {@code adb} -port 5555. Subsequent instances use port numbers increasing by two — for example, 5556/5557, -5558/5559, and so on. Up to 16 concurrent emulator instances can run a console facility.
- -To connect to the emulator console, you must specify a valid console port. If multiple emulator instances are running, you need to determine the console port of the emulator instance you want to connect to. You can find the instance's console port listed in the title of the instance window. For example, here's the window title for an instance whose console port is 5554:
- -Android Emulator (5554)
Alternatively, you can use the adb devices command, which prints a list of running emulator instances and their console port numbers. For more information, see Querying for Emulator/Device Instances in the adb documentation.
Note: The emulator listens for connections on ports 5554-5587 and accepts connections only from localhost.
- -Once you are connected to the console, you can then enter help [command] to see a list of console commands and learn about specific commands.
To exit the console session, use quit or exit.
The following sections below describe the major functional areas of the console.
- - -You can use the console to add and remove port redirection while the emulator is running. After -you connect to the console, manage port redirection by entering the following command:
- -redir <list|add|del>- -
The redir command supports the subcommands listed in the table below.
| Subcommand - | Description | -Comments | -
|---|---|---|
list |
- List the current port redirection. | -- |
add <protocol>:<host-port>:<guest-port> |
- Add a new port redirection. | -
|
-
del <protocol>:<host-port> |
- Delete a port redirection. | -The meanings of <protocol> and <host-port> are listed in the previous row. | -
You can use the console to set the geographic location reported to the applications running
-inside an emulator. Use the geo command to send a simple GPS fix to the
-emulator, with or without NMEA 1083 formatting:
geo <fix|nmea>- -
The geo command supports the subcommands listed in the table below.
| Subcommand | -Description | -Comments | -
|---|---|---|
fix <longitude> <latitude> [<altitude>] |
- Send a simple GPS fix to the emulator instance. | -Specify longitude and latitude in decimal degrees. Specify altitude in meters. | -
nmea <sentence> |
- Send an NMEA 0183 sentence to the emulated device, as if it were sent from an emulated GPS modem. | -<sentence> must begin with '$GP'. Only '$GPGGA' and '$GPRCM' sentences are currently supported. |
-
You can issue the geo command as soon as an emulator instance is running. The
-emulator sets the location you enter by creating a mock location provider. This provider responds to
-location listeners set by applications, and also supplies the location to the {@link
-android.location.LocationManager}. Any application can query the location manager to obtain the
-current GPS fix for the emulated device by calling:
-
-
LocationManager.getLastKnownLocation("gps")
-
-For more information about the Location Manager, see {@link android.location.LocationManager}. -
- -The {@code event} console commands sends hardware events to the emulator. The syntax for this -command is as follows:
- -event <send|types|codes|text>- -
The event command supports the subcommands listed in the table below.
| Subcommand - | Description | -Comments | -
|---|---|---|
send <type>:<code>:<value> [...] |
- Send one or more events to the Android kernel. | -You can use text names or integers for <type> and <value>. |
-
types |
- List all <type> string aliases supported by the event subcommands. |
-- |
codes <type> |
- List all <codes> string aliases supported by the event
- subcommands for the specified <type>. |
-- |
event text <message> |
- Simulate keypresses to send the specified string of characters as a message, | -The message must be a UTF-8 string. Unicode posts will be reverse-mapped according to the current device keyboard. Unsupported characters will be discarded silently. | -
The {@code power} command controls the power state reported by the emulator to applications. The -syntax for this command is as follows:
- -power <display|ac|status|present|health|capacity>- -
The event command supports the subcommands listed in the table below.
| Subcommand | -Description | -Comments | -
|---|---|---|
display |
- Display battery and charger state. | -- |
ac <on|off> |
- Set AC charging state to on or off. | -- |
status <unknown|charging|discharging|not-charging|full> |
- Change battery status as specified. | -- |
present <true|false> |
- Set battery presence state. | -- |
health <unknown|good|overheat|dead|overvoltage|failure> |
- Set battery health state. | -- |
capacity <percent> |
- Set remaining battery capacity state (0-100). | -- |
You can use the console to check the network status and current delay and speed characteristics. To do so, connect to the console and use the netstatus command. Here's an example of the command and its output.
network status -- - -
The emulator lets you simulate various network latency levels, so that you can test your -application in an environment more typical of the actual conditions in which it will run. You can -set a latency level or range at emulator startup or you can use the console to change the latency, -while the application is running in the emulator.
- -To set latency at emulator startup, use the -netdelay emulator option with a
-supported <delay> value, as listed in the table below. Here are some
-examples:
emulator -netdelay gprs -emulator -netdelay 40 100- -
To make changes to network delay while the emulator is running, connect to the console and use
-the netdelay command with a supported <delay> value from the table
-below.
network delay gprs- -
The format of network <delay> is one of the following (numbers are milliseconds):
- -| Value | -Description | Comments |
|---|---|---|
gprs | GPRS | -(min 150, max 550) | -
edge | EDGE/EGPRS | -(min 80, max 400) | -
umts | UMTS/3G | -(min 35, max 200) | -
none | No latency | (min 0, max 0) |
<num> |
-Emulate an exact latency (milliseconds). | -|
<min>:<max> |
-Emulate an specified latency range (min, max milliseconds). | -
The emulator also lets you simulate various network transfer rates. -You can set a transfer rate or range at emulator startup or you can use the console to change the -rate, while the application is running in the emulator.
- -To set the network speed at emulator startup, use the -netspeed emulator option with a supported
-<speed> value, as listed in the table below. Here are some examples:
emulator -netspeed gsm -emulator -netspeed 14.4 80- -
To make changes to network speed while the emulator is running, connect to the console and use
-the netspeed command with a supported <speed> value from the table
-below.
network speed 14.4 80- -
The format of network <speed> is one of the following (numbers are
-kilobits/sec):
| Value | -Description | Comments |
|---|---|---|
gsm |
- GSM/CSD | (Up: 14.4, down: 14.4) |
hscsd |
- HSCSD | (Up: 14.4, down: 43.2) |
gprs |
- GPRS | (Up: 40.0, down: 80.0) |
edge |
- EDGE/EGPRS | -(Up: 118.4, down: 236.8) | -
umts |
- UMTS/3G | (Up: 128.0, down: 1920.0) |
hsdpa |
- HSDPA | (Up: 348.0, down: 14400.0) |
full |
- no limit | (Up: 0.0, down: 0.0) |
<num> |
- Set an exact rate used for both upload and download. | |
<up>:<down> |
- Set exact rates for upload and download separately. |
The Android emulator includes its own GSM emulated modem that lets you simulate telephony -functions in the emulator. For example, you can simulate inbound phone calls, establish data -connections and terminate them. The Android system handles simulated calls exactly as it would -actual calls. The emulator does not support call audio.
- -You can use the {@code gsm} command to access the emulator's telephony functions after connecting -to the console. The syntax for this command is as follows:
- -gsm <call|accept|busy|cancel|data|hold|list|voice|status>- -
The gsm command supports the subcommands listed in the table below.
| Subcommand | -Description | -Comments | -
|---|---|---|
call <phonenumber> |
- Simulate an inbound phone call from <phonenumber>. | -- |
accept <phonenumber> |
- Accept an inbound call from <phonenumber> and change the call's state "active". | -You can change a call's state to "active" only if its current state is "waiting" or "held". | -
busy <phonenumber> |
- Close an outbound call to <phonenumber> and change the call's state to "busy". | -You can change a call's state to "busy" only if its current state is "waiting". | -
cancel <phonenumber> |
- Terminate an inbound or outbound phone call to/from <phonenumber>. | -- |
data <state> |
- Change the state of the GPRS data connection to <state>. | -Supported <state> values are: -
|
-
hold |
- Change the state of a call to "held". | -You can change a call's state to "held" only if its current state is "active" or "waiting". | -
list |
- List all inbound and outbound calls and their states. | -- |
voice <state> |
- Change the state of the GPRS voice connection to <state>. | -Supported <state> values are: -
|
-
status |
- Report the current GSM voice/data state. | -Values are those described for the voice and data commands. |
-
The Android emulator console lets you generate an SMS message and direct it to an emulator -instance. Once you connect to an emulator instance, you can generate an emulated incoming SMS using -the following command:
- -sms send <senderPhoneNumber> <textmessage>- -
where <senderPhoneNumber> contains an arbitrary numeric string.
The console forwards the SMS message to the Android framework, which passes it through to an application that handles that message type.
- - -You can use the vm command to control the VM on an emulator instance. The syntax for
-this command is as follows:
vm <start|stop|status>- -
The vm command supports the subcommands listed in the table below.
| Subcommand | -Description | -Comments | -
|---|---|---|
start |
- Start the VM on the instance. | -- |
stop |
- Stop the VM on the instance. | -- |
start |
- Display the current status of the VM (running or stopped). | -- |
You can use the window command to manage the emulator window. The syntax for this
-command is as follows:
window <scale>- -
The vm command supports the subcommands listed in the table below.
| Subcommand | -Description | -Comments | -
|---|---|---|
scale <scale> |
- Scale the emulator window. | -A number between 0.1 and 3 that sets the scaling factor. You can - also specify scale as a DPI value if you add the suffix "dpi" to the scale value. A value of "auto" - tells the emulator to select the best window size. | -
You can terminate an emulator instance through the console, using the kill command.
The {@code adb} utility sees the emulator as an actual physical device. For this reason, you
-might have to use the {@code -d} flag with some common {@code adb} commands, such as
-install. The {@code -d} flag lets you specify which of several connected devices to use
-as the target of a command. If you don't specify {@code -d}, the emulator targets the first
-device in its list. For more information about {@code adb}, see Android Debug Bridge.
For emulators running on Mac OS X, if you see an error {@code Warning: No DNS servers found}
-when starting the emulator, check to see whether you have an /etc/resolv.conf file. If
-not, please run the following line in a command window:
ln -s /private/var/run/resolv.conf /etc/resolv.conf- -
See Frequently Asked Questions for more -troubleshooting information.
diff --git a/docs/html/tools/help/etc1tool.jd b/docs/html/tools/help/etc1tool.jd deleted file mode 100644 index a7f76f5cadb612f85f7dcfb941885e1d7f330062..0000000000000000000000000000000000000000 --- a/docs/html/tools/help/etc1tool.jd +++ /dev/null @@ -1,68 +0,0 @@ -page.title=etc1tool -parent.title=Tools -parent.link=index.html -@jd:body - - -etc1tool is a command line utility that lets you encode PNG
- images to the ETC1 compression standard and decode ETC1 compressed images back to PNG.
The usage for etc1tool is:
etc1tool infile [--help | --encode | --encodeNoHeader | --decode] [--showDifference -diff-file] [-o outfile]- -
| Option | - -Description | -
|---|---|
infile |
-
- The input file to compress | -
--help |
-
- Print usage information | -
--encode |
-
- Create an ETC1 file from a PNG file. - This is the default mode for the tool if nothing is specified. | -
--encodeNoHeader |
-
- Create a raw ETC1 data file (without a header) from a PNG file. | -
--decode |
-
- Create a PNG file from an ETC1 file | -
--showDifference diff-file |
-
- Write the difference between the original and encoded image to
- diff-file (only valid when encoding). |
-
-o outfile |
-
- Specify the name of the output file.
- If outfile is not specified, the output file is constructed
- from the input filename with the appropriate suffix (.pkm or .png).
- |
-
Tracer is a tool for analyzing OpenGL for Embedded Systems (ES) code in your Android application. -The tool allows you to capture OpenGL ES commands and frame by frame images to help you understand -how your graphics commands are being executed.
- -Note: The Tracer tool requires a device running Android 4.1 (API -Level 16) or higher.
- - -To run Tracer in Device Monitor:
- -Tracer captures OpenGL ES command execution logs and can also capture progressive images of the -frames generated by those commands to enable you to perform logical and visual analysis of your -OpenGL ES code. The Tracer tool operates by connecting to a device running Android 4.1 (API Level -16) or higher that is running the application you want to analyze. The Tracer tool captures trace -information while the application is running and saves it to a {@code .gltrace} file for -analysis.
- -
-Figure 1. Trace capture dialog box.
- -To capture an OpenGL ES trace for an Android application:
- -Note: If you are tracing the default activity for the -application, you can leave this field blank.
-Note: If you want to capture progressive frame images for each -drawing call, enable the Read back currently bound framebuffer on glDraw*() option. -Be aware that using this option can result in large trace files.
-After you have generated a trace, you can load it for review and analysis.
- -To review a captured trace:
- -The Hierarchy Viewer allows you to debug and optimize your user -interface. It provides a visual representation of the layout's View hierarchy -(the Layout View) and a magnified inspector of the display (the Pixel Perfect View).
- -To start the Hierarchy Viewer, do one of the following:
- -
. Click the Open Perspectives
-icon 
and select
-Hierarchy View. tools/ directory, enter:
- monitor
For more information on how to use the Hierarchy Viewer, see -Optimizing Your UI. -
- -Note: The command line version of Hierarchy Viewer has been -deprecated.
- - diff --git a/docs/html/tools/help/hprof-conv.jd b/docs/html/tools/help/hprof-conv.jd deleted file mode 100644 index 89d6a68ec1c696ac3b2c283612a186a448887601..0000000000000000000000000000000000000000 --- a/docs/html/tools/help/hprof-conv.jd +++ /dev/null @@ -1,26 +0,0 @@ -page.title=HPROF Converter -parent.title=Tools -parent.link=index.html -@jd:body - -
-The hprof-conv tool converts the HPROF file that is
-generated by the Android SDK tools to a standard format so you
-can view the file in a profiling tool of your choice.
hprof-conv [-z] <infile> <outfile>- -
-You can use "-" for <infile> or <outfile>
-to specify stdin or stdout.
-
-You can use "-z" to filter out zygote allocations shared by all applications. -
- -Note: Android Studio provides integrated access to this conversion -process. To convert a heap dump to standard HPROF format in Android Studio, right-click a heap -snapshot in the Captures view and select Export to standard .hprof.
- - diff --git a/docs/html/tools/help/image-asset-studio.jd b/docs/html/tools/help/image-asset-studio.jd deleted file mode 100644 index 818b7442007f4a3275c2cfe697d66d4bb77dc0fb..0000000000000000000000000000000000000000 --- a/docs/html/tools/help/image-asset-studio.jd +++ /dev/null @@ -1,200 +0,0 @@ -page.title=Image Asset Studio -parent.title=Tools -parent.link=index.html -page.tags=image asset -@jd:body -Image Asset Studio helps you to generate custom icons for your Android applications from existing
- image, clipart, or text-string resources. It generates a set of icons at the appropriate resolution
- for each generalized screen
- density that your app supports.
- The newly generated icons are placed in density-specific folders (for example, mipmap-mdpi/
- or drawable-xxxhdpi/), which
- reside in the application’s res/ folder. At runtime, Android uses the appropriate
- resource based on the screen density of the device your application is running on.
Image Asset Studio generates the following asset types:
-This guide shows how to generate these assets using Image Asset Studio.
- -Follow these steps to access Image Asset Studio:
-res/folder and select New > Image
-Asset. The Image Asset Studio window appears.You can generate icons from image, clipart -, or text-string resources. This section explains how to work with -each of these resources. -
- - -The icon to be generated appears in the Preview pane, displayed at sizes corresponding - to different screen densities.
- -The rest of the settings on this screen are optional. -To learn how to customize your icons using these options, - see Customizing Icons.
The icon to be generated appears in the Preview pane, displayed at sizes corresponding -to different screen densities.
-The rest of the settings on this screen are optional. - To learn how to customize your icons using these options, - see Customizing Icons.
The icon to be generated appears in the Preview pane, displayed at sizes corresponding -to different screen densities.
The rest of the settings on this screen are optional. -To learn how to customize your icons using these options, -see Customizing Icons.
Image Asset Studio lets you customize various visual effects for your icons. The following options -are of particular note.
- -
- This section explains how to save your icons to the res/ folder. Do so by following
- these steps:
Note: Launcher icon files reside in a different location from that
- of other icons. They are located in the mipmap/ folder. All other icon files reside
- in the drawable/ folder of your project.
To change the module and resource directory, follow these steps:
-src/main/res: This source set applies to all build variants, including debug
- and release.src/debug/res, src/release/res: These source sets override the main
- source set and apply to one version of a build. The debug source set is for debugging only.
- After you have an image resource in the res/directory of your project, you can
- reference it from your Java code or your XML layout using its
-
- resource ID.
For example, the following XML references the ic_launcher icon in the
-mipmap/ folder.
-<application android:name="ApplicationTitle" - android:label="@string/app_label" - android:icon="@mipmap/ic_launcher" >- -
The following Java code sets an
-ImageView to use
- the drawable/myimage.png resource:
ImageView imageView = (ImageView) findViewById(R.id.myimageview); -imageView.setImageResource(R.drawable.myimage);diff --git a/docs/html/tools/help/index.jd b/docs/html/tools/help/index.jd deleted file mode 100755 index 411f908463ba567168ba0591528d1bffa98ee619..0000000000000000000000000000000000000000 --- a/docs/html/tools/help/index.jd +++ /dev/null @@ -1,176 +0,0 @@ -page.title=Tools Help -@jd:body - - -
The Android SDK includes a variety of tools that help you develop mobile -applications for the Android platform. The tools are classified into two groups: SDK tools -and platform tools. SDK tools are platform independent and are required no matter which -Android platform you are developing on. Platform tools are customized to support the features of the -latest Android platform.
- - -The SDK tools are installed with the SDK starter package and are periodically updated.
-The SDK tools are required if you are developing Android applications. The most important SDK tools
-include the Android SDK Manager (android sdk), the AVD Manager (android
-avd) the emulator (emulator), and the Dalvik Debug Monitor Server
-(ddms). A short summary of some frequently-used SDK tools is provided below.
dmtracedump. For more information on using dmtracedump, see Profiling
-with Traceview and dmtracedump.apk files by ensuring that all uncompressed data starts with a
-particular alignment relative to the start of the file. This should always be used to align .apk
-files after they have been signed.The platform tools are typically updated every time you install a new SDK platform. Each update
-of the platform tools is backward compatible with older platforms. Usually, you directly use only
-one of the platform tools—the Android Debug Bridge (adb).
-Android Debug Bridge is a versatile tool that lets you manage the state of an emulator instance or
-Android-powered device. You can also use it to install an Android application (.apk) file on a
-device.
The other platform tools, such as aidl,
-aapt, dexdump, and dx, are typically called by the Android
-build tools, so you rarely need to invoke these tools directly.
-As a general rule, you should rely on the build tools to call them as needed.
Note: The Android SDK provides additional shell tools that can
-be accessed through adb, such as bmgr and
-logcat.
The {@code jobb} tool allows you to build encrypted and unencrypted APK expansion files in - Opaque Binary Blob (OBB) format. You can download and mount these expansion files in your - application using {@link android.os.storage.StorageManager} on devices with Android 2.3 (API - Level 9) or higher. OBB files are used to provide additional file assets for Android applications - (such as graphics, sounds and video), separate from an application's APK file. For more - information on using expansion files, see - APK Expansion Files.
- - -The syntax for running {@code jobb} is as follows:
- --jobb [-d <directory>][-o <filename>][-pn <package>][-pv <version>] \ - [-k <key>][-ov][-dump <filename>][-v][-about] -- -
You can use the {@code jobb} tool to create an OBB file or extract the contents of an -existing OBB. The following example command creates an OBB file from source files.
- --$ jobb -d /temp/assets/ -o my-app-assets.obb -k secret-key -pn com.my.app.package -pv 11 -- -
This example shows how to dump (extract) the contents of an existing OBB file:
- --$ jobb -d /temp/obb-output/ -o my-app-assets.obb -k secret-key -- - -
The table below lists the command line options for the {@code jobb} tool.
- -| Option | -Description | -
|---|---|
| {@code -d <directory>} | -Set the input directory for creating an OBB file, or the output directory when extracting - ({@code -dump}) an existing file. When creating an OBB file, the contents of the specified - directory and all its sub-directories are included in the OBB file system. - | -
| {@code -o <filename>} | -Specify the filename for the OBB file. This parameter is required when - creating an OBB and extracting (dumping) its contents. | -
| {@code -pn <package>} | -Specify the package name for the application that mounts the OBB file, which corresponds - to the {@code package} value specified in your application's manifest. This parameter is - required when creating an OBB file. | -
| {@code -pv <version>} | -Set the minimum version for the application that can mount the OBB file, which corresponds - to the {@code android:versionCode} value in your application's manifest. This parameter is - required when creating an OBB file. | -
| {@code -k <key>} | -Specify a password for encrypting a new OBB file or decrypting an existing, encypted - OBB file. | -
| {@code -ov} | -Create OBB file that is an overlay of an existing OBB file structure. This option allows - the new package contents to be mounted into the same location as a previous package and is - intended for creating patch versions of previously generated OBB files. Files within an - overlay OBB file replace files that have the same path. | -
| {@code -dump <filename>} | -Extract the contents of the specified OBB file. When using this option, you must also - specify the output directory for the contents using the {@code -d <directory>} - parameter. - -Note: When dumping an existing OBB file, you can omit the - {@code -d <directory>} parameter to get a listing of the directories inside the file, - without extracting the contents. - |
-
| {@code -v} | -Set verbose output for the tool. | -
| {@code -about} | -Display version and help information for the {@code jobb} tool. | -
Note: The Android layoutopt tool has been replaced
-by the {@code lint} tool beginning in SDK Tools revision 16. The {@code lint} tool reports UI
-layout performance issues in a similar way as layoutopt, and detects additional problems.
For more information about using {@code lint}, see -Improving Your Code with lint and the -lint reference documentation.
- -layoutopt is a command-line tool that helps you optimize the
-layouts and layout hierarchies of your applications.
- -
This document is a reference to the available command line options. For more information and -sample -output of the tool, see Optimizing layouts with -layoutopt.
- -To run layoutopt against a given list of layout resources:
layoutopt <file_or_directory> ...- -
For example:
- -$ layoutopt res/layout-land-
$ layoutopt res/layout/main.xml res/layout-land/main.xml- diff --git a/docs/html/tools/help/lint.jd b/docs/html/tools/help/lint.jd deleted file mode 100644 index 0f52689b3342663bb25f771e73cbdf89889a9496..0000000000000000000000000000000000000000 --- a/docs/html/tools/help/lint.jd +++ /dev/null @@ -1,191 +0,0 @@ -page.title=lint -parent.title=Tools -parent.link=index.html -@jd:body - -
The Android {@code lint} tool is a static code analysis tool that checks your Android project source files for potential bugs and optimization improvements for correctness, security, performance, usability, accessibility, and internationalization.
- -In Android Studio, the configured lint and other IDE inspections run automatically
-whenever you compile your program. You can also manually run inspections in Android Studio
-by selecting Analyze > Inspect Code from the application or right-click menu.
-The Specify Inspections Scope dialog appears so you can specify the desired inspection
-profile and scope.
For more information on enabling {@code lint} inspections and running {@code lint}, -see Improving Your Code with lint.
- --
lint [flags] <project directory>- -For example, you can issue the following command to scan the Java and XML files under the -{@code myproject} directory and its subdirectories. The result is displayed on the console. -
lint myproject- -You can also use {@code lint} to check for a specific issue. For example, you can run the following command to scan the files under the {@code myproject} directory and its subdirectories to check for XML attributes missing the Android namespace prefix. The issue ID {@code MissingPrefix} tells lint to only scan for this issue. -
lint --check MissingPrefix myproject- -You can create an HTML report for the issues that {@code lint} detects. For example, you can run the following command to scan the {@code myproject} directory and its subdirectories for accessibility issues, then generate an HTML report in the {@code accessibility_report.html} file. -
lint --check Accessibility --HTML accessibility_report.html myproject- - -
Table 1 describes the command-line options for {@code lint}.
-- Table 1. Command-line options for lint
-| Category | -Option | -Description | -Comments | -
|---|---|---|---|
| Checking | ---disable <list> |
-Disable checking for a specific list of issues. | -The <list> must be a comma-separated list of {@code lint} issue IDs or categories. |
-
--enable <list> |
-Check for all the default issues supported by {@code lint} as well as the specifically enabled list of issues. | -The <list> must be a comma-separated list of {@code lint} issue IDs or categories. |
-|
--check <list> |
-Check for a specific list of issues. | -The <list> must be a comma-separated list of {@code lint} issue IDs or categories. |
-|
-w or --nowarn |
-Only check for errors and ignore warnings | -- | |
-Wall |
-Check for all warnings, including those that are disabled by default | -- | |
-Werror |
-Report all warnings as errors | -- | |
--config <filename> |
-Use the specified configuration file to determine if issues are enabled or disabled for {@code lint} checking | -If the project contains a {@code lint.xml} file, the {@code lint.xml} file will be used as the configuration file by default. | -|
| Reporting | ---html <filename> |
-Generate an HTML report. | -The report is saved in the output file specified in the argument. The HTML output includes code snippets of the source code where {@code lint} detected an issue, a verbose description of the issue found, and links to the source file. | -
--url <filepath>=<url> |
-In the HTML output, replace a local path prefix <filepath> with a url prefix <url>. |
-The {@code --url} option only applies when you are generating an HTML report with the {@code --html} option. You can specify multiple <filepath>=<url> mappings in the argument by separating each mapping with a comma. To turn off linking to files, use {@code --url none} |
-|
--simplehtml <filename> |
-Generate a simple HTML report | -The report is saved in the output file specified in the argument. | -|
--xml <filename> |
-Generate an XML report | -The report is saved in the output file specified in the argument. | -|
--fullpath |
-Show the full file paths in the {@code lint} checking results. | -- | |
--showall |
-Don't truncate long messages or lists of alternate locations. | -- | |
--nolines |
-Don't include code snippets from the source files in the output. | -- | |
--exitcode |
-Set the exit code to 1 if errors are found. | -- | |
--quiet |
-Don't show the progress indicator. | -- | |
| Help | ---help |
-List the command-line arguments supported by the {@code lint} tool. | -Use {@code --help <topic>} to see help information for a specific topic, such as "suppress". | -
--list |
-List the ID and short description for issues that can be checked by {@code lint} | -- | |
--show |
-List the ID and verbose description for issues that can be checked by {@code lint} | -Use {@code --show <ids>} to see descriptions for a specific list of {@code lint} issue IDs. | -|
--version |
-Show the {@code lint} version | -- |
To configure lint checking, you can apply the following annotation or attribute to the source files in your Android project.
-@SuppressLint
-annotation. tools:ignore attribute. You can also specify your {@code lint} checking preferences for a specific Android project in
-the lint.xml file. For more information on configuring {@code lint}, see
-Improving Your Code with lint.
The Android logging system provides a mechanism for collecting and viewing system debug
- output. Logs from various applications and portions of the system are collected in a series of
- circular buffers, which then can be viewed and filtered by the logcat command. You can use
- logcat from an ADB shell to view the log messages.
For complete information about logcat options and filtering specifications, see - Reading and Writing Logs.
- -For more information on accessing logcat from DDMS, instead of the command line, see
- Using DDMS.
-[adb] logcat [<option>] ... [<filter-spec>] ... -- -
You can run logcat as an adb command or directly in a shell prompt
- of your emulator or connected device. To view log output using adb, navigate to your SDK
- platform-tools/ directory and execute:
-$ adb logcat -- -
You can create a shell connection to a device and execute:
--$ adb shell -# logcat -- -
The following table describes the command line options of logcat.
| Option | - -Description | -
|---|---|
-b <buffer> |
-
- Loads an alternate log buffer for viewing, such as events or
- radio. The main buffer is used by default. See Viewing Alternative Log Buffers. |
-
-c |
-
- Clears (flushes) the entire log and exits. | -
-d |
-
- Dumps the log to the screen and exits. | -
-f <filename> |
-
- Writes log message output to <filename>. The default is
- stdout. |
-
-g |
-
- Prints the size of the specified log buffer and exits. | -
-n <count> |
-
- Sets the maximum number of rotated logs to <count>. The default value
- is 4. Requires the -r option. |
-
-r <kbytes> |
-
- Rotates the log file every <kbytes> of output. The default value is
- 16. Requires the -f option. |
-
-s |
-
- Sets the default filter spec to silent. | -
-v <format> |
-
- Sets the output format for log messages. The default is brief format. For a
- list of supported formats, see Controlling Log Output
- Format. |
-
The mksdcard tool lets you quickly create a FAT32 disk image that you can load in the
- emulator, to simulate the presence of an SD card in the device. Because you can specify an SD
- card while creating an AVD in the AVD Manager, you usually use that feature to create an SD card.
- This tool creates an SD card that is not bundled with an AVD, so it is useful for situations
- where you need to share a virtual SD card between multiple emulators.
-mksdcard -l <label> <size> <file> -- -
The following table describes the command-line options of mksdcard
| Option | - -Description | -
|---|---|
-l |
-
- A volume label for the disk image to create. | -
size |
-
- An integer that specifies the size (in bytes) of disk image to create. You can also
- specify size in kilobytes or megabytes, by appending a "K" or "M" to <size>. For
- example, 1048576K, 1024M. |
-
file |
-
- The path/filename of the disk image to create. | -
Once you have created the disk image file, you can load it in the emulator at startup using
- the emulator's -sdcard option. For more information, see Android Emulator.
The usage for the -sdcard option is as follows:
emulator -sdcard <file>- -
mksdcard -l mySdCard 1024M mySdCardFile.img\ No newline at end of file diff --git a/docs/html/tools/help/monitor.jd b/docs/html/tools/help/monitor.jd deleted file mode 100755 index 3541cc30d928546f284ef3198d8989dc57dba3bb..0000000000000000000000000000000000000000 --- a/docs/html/tools/help/monitor.jd +++ /dev/null @@ -1,51 +0,0 @@ -page.title=Device Monitor -@jd:body - -
Android Device Monitor is a stand-alone tool that provides a graphical user interface for -several Android application debugging and analysis tools. The Monitor tool does not -require installation of an integrated development environment, such as Android Studio, and -encapsulates the following tools:
- -To start Device Monitor:
- -.
- tools/ directory, enter the following command:
- monitor-
Start an Android emulator or connect an Android device via USB cable, and connect Device -Monitor to the device by selecting it in the Devices window.
- -Note: Only one debugger can be connected to your device at a time.
diff --git a/docs/html/tools/help/monkey.jd b/docs/html/tools/help/monkey.jd deleted file mode 100644 index 941f5d9696b0d122ec866878144c414aa98d5d22..0000000000000000000000000000000000000000 --- a/docs/html/tools/help/monkey.jd +++ /dev/null @@ -1,242 +0,0 @@ -page.title=UI/Application Exerciser Monkey -parent.title=Tools -parent.link=index.html -@jd:body - -The Monkey is a program that runs on your -emulator or device and generates pseudo-random -streams of user events such as clicks, touches, or gestures, as well as a number of system-level -events. You can use the Monkey to stress-test applications that you are developing, in a random -yet repeatable manner.
- - -The Monkey is a command-line tool that you can run on any emulator -instance or on a device. It sends a pseudo-random stream of -user events into the system, which acts as a stress test on the application software you are -developing.
- -The Monkey includes a number of options, but they break down into four primary -categories:
- -When the Monkey runs, it generates events and sends them to the system. It also watches -the system under test and looks for three conditions, which it treats specially:
- -Depending on the verbosity level you have selected, you will also see reports on the progress -of the Monkey and the events being generated.
- - -You can launch the Monkey using a command line on your development machine or from a script.
-Because the Monkey runs in the emulator/device environment, you must launch it from a shell in
-that environment. You can do this by prefacing adb shell to each command,
-or by entering the shell and entering Monkey commands directly.
The basic syntax is:
- -$ adb shell monkey [options] <event-count>- -
With no options specified, the Monkey will launch in a quiet (non-verbose) mode, and will send -events to any (and all) packages installed on your target. Here is a more typical command line, -which will launch your application and send 500 pseudo-random events to it:
- -$ adb shell monkey -p your.package.name -v 500- - -
The table below lists all options you can include on the Monkey command line.
- -| Category | -Option | -Description | -
|---|---|---|
| General | ---help |
-Prints a simple usage guide. | -
-v |
-Each -v on the command line will increment the verbosity level. -Level 0 (the default) provides little information beyond startup notification, test completion, and -final results. -Level 1 provides more details about the test as it runs, such as individual events being sent to -your activities. -Level 2 provides more detailed setup information such as activities selected or not selected for -testing. | -|
| Events | --s <seed> |
-Seed value for pseudo-random number generator. If you re-run the Monkey with the same seed -value, it will generate the same sequence of events. | -
--throttle <milliseconds> |
-Inserts a fixed delay between events. You can use this option to slow down the Monkey. -If not specified, there is no delay and the events are generated as rapidly as possible. | -|
--pct-touch <percent> |
-Adjust percentage of touch events. -(Touch events are a down-up event in a single place on the screen.) | -|
--pct-motion <percent> |
-Adjust percentage of motion events. -(Motion events consist of a down event somewhere on the screen, a series of pseudo-random -movements, and an up event.) | -|
--pct-trackball <percent> |
-Adjust percentage of trackball events. -(Trackball events consist of one or more random movements, sometimes followed by a click.) | -|
--pct-nav <percent> |
-Adjust percentage of "basic" navigation events. -(Navigation events consist of up/down/left/right, as input from a directional input device.) | -|
--pct-majornav <percent> |
-Adjust percentage of "major" navigation events. -(These are navigation events that will typically cause actions within your UI, such as -the center button in a 5-way pad, the back key, or the menu key.) | -|
--pct-syskeys <percent> |
-Adjust percentage of "system" key events. -(These are keys that are generally reserved for use by the system, such as Home, Back, Start Call, -End Call, or Volume controls.) | -|
--pct-appswitch <percent> |
-Adjust percentage of activity launches. At random intervals, the Monkey will issue a startActivity() call, as a way of maximizing -coverage of all activities within your package. | -|
--pct-anyevent <percent> |
-Adjust percentage of other types of events. This is a catch-all for all other types of events such as keypresses, other less-used -buttons on the device, and so forth. | -|
| Constraints | --p <allowed-package-name> |
-If you specify one or more packages this way, the Monkey will only allow the system -to visit activities within those packages. If your application requires access to activities in -other packages (e.g. to select a contact) you'll need to specify those packages as well. -If you don't specify any packages, the Monkey will allow the system to launch activities -in all packages. To specify multiple packages, use the -p option multiple times — one -p -option per package. | -
-c <main-category> |
-If you specify one or more categories this way, the Monkey will only allow the -system to visit activities that are listed with one of the specified categories. -If you don't specify any categories, the Monkey will select activities listed with the category -Intent.CATEGORY_LAUNCHER or Intent.CATEGORY_MONKEY. To specify multiple categories, use the -c -option multiple times — one -c option per category. | -|
| Debugging | ---dbg-no-events |
-When specified, the Monkey will perform the initial launch into a test activity, but -will not generate any further events. -For best results, combine with -v, one or more package constraints, and a non-zero throttle to keep the Monkey -running for 30 seconds or more. This provides an environment in which you can monitor package -transitions invoked by your application. | -
--hprof |
-If set, this option will generate profiling reports immediately before and after -the Monkey event sequence. -This will generate large (~5Mb) files in data/misc, so use with care. See -Traceview for more information -on trace files. | -|
--ignore-crashes |
-Normally, the Monkey will stop when the application crashes or experiences any type of -unhandled exception. If you specify this option, the Monkey will continue to send events to -the system, until the count is completed. | -|
--ignore-timeouts |
-Normally, the Monkey will stop when the application experiences any type of timeout error such -as a "Application Not Responding" dialog. If you specify this option, the Monkey will continue to -send events to the system, until the count is completed. | -|
--ignore-security-exceptions |
-Normally, the Monkey will stop when the application experiences any type of permissions error, -for example if it attempts to launch an activity that requires certain permissions. If you specify -this option, the Monkey will continue to send events to the system, until the count is -completed. | -|
--kill-process-after-error |
-Normally, when the Monkey stops due to an error, the application that failed will be left -running. When this option is set, it will signal the system to stop the process in which the error -occurred. -Note, under a normal (successful) completion, the launched process(es) are not stopped, and -the device is simply left in the last state after the final event. | -|
--monitor-native-crashes |
-Watches for and reports crashes occurring in the Android system native code. If --kill-process-after-error is set, the system will stop. | -|
--wait-dbg |
-Stops the Monkey from executing until a debugger is attached to it. | -
- The monkeyrunner tool provides an API for writing programs that control an Android device - or emulator from outside of Android code. With monkeyrunner, you can write a Python program - that installs an Android application or test package, runs it, sends keystrokes to it, - takes screenshots of its user interface, and stores screenshots on the workstation. The - monkeyrunner tool is primarily designed to test applications and devices at the - functional/framework level and for running unit test suites, but you are free to use it for - other purposes. -
-
- The monkeyrunner tool is not related to the
- UI/Application Exerciser Monkey,
- also known as the monkey tool. The monkey tool runs in an
- adb shell directly on the
- device or emulator and generates pseudo-random streams of user and system events. In comparison,
- the monkeyrunner tool controls devices and emulators from a workstation by sending specific
- commands and events from an API.
-
- The monkeyrunner tool provides these unique features for Android testing: -
-os and
- subprocess
- modules to call Android tools such as
- Android Debug Bridge.
- - You can also add your own classes to the monkeyrunner API. This is described - in more detail in the section - Extending monkeyrunner with plugins. -
-- The monkeyrunner tool uses Jython, a - implementation of Python that uses the Java programming language. Jython allows the - monkeyrunner API to interact easily with the Android framework. With Jython you can - use Python syntax to access the constants, classes, and methods of the API. -
- -
- Here is a simple monkeyrunner program that connects to a device, creating a
- MonkeyDevice
- object. Using the MonkeyDevice object, the program installs an Android application
- package, runs one of its activities, and sends key events to the activity.
- The program then takes a screenshot of the result, creating a
- MonkeyImage object.
- From this object, the program writes out a .png file containing the screenshot.
-
-# Imports the monkeyrunner modules used by this program
-from com.android.monkeyrunner import MonkeyRunner, MonkeyDevice
-
-# Connects to the current device, returning a MonkeyDevice object
-device = MonkeyRunner.waitForConnection()
-
-# Installs the Android package. Notice that this method returns a boolean, so you can test
-# to see if the installation worked.
-device.installPackage('myproject/bin/MyApplication.apk')
-
-# sets a variable with the package's internal name
-package = 'com.example.android.myapplication'
-
-# sets a variable with the name of an Activity in the package
-activity = 'com.example.android.myapplication.MainActivity'
-
-# sets the name of the component to start
-runComponent = package + '/' + activity
-
-# Runs the component
-device.startActivity(component=runComponent)
-
-# Presses the Menu button
-device.press('KEYCODE_MENU', MonkeyDevice.DOWN_AND_UP)
-
-# Takes a screenshot
-result = device.takeSnapshot()
-
-# Writes the screenshot to a file
-result.writeToFile('myproject/shot1.png','png')
-
-
-
- The monkeyrunner API is contained in three modules in the package
- com.android.monkeyrunner:
-
MonkeyRunner:
- A class of utility methods for monkeyrunner programs. This class provides a method for
- connecting monkeyrunner to a device or emulator. It also provides methods for
- creating UIs for a monkeyrunner program and for displaying the built-in help.
- MonkeyDevice:
- Represents a device or emulator. This class provides methods for installing and
- uninstalling packages, starting an Activity, and sending keyboard or touch events to an
- application. You also use this class to run test packages.
- MonkeyImage:
- Represents a screen capture image. This class provides methods for capturing screens,
- converting bitmap images to various formats, comparing two MonkeyImage objects, and
- writing an image to a file.
-
- In a Python program, you access each class as a Python module. The monkeyrunner tool
- does not import these modules automatically. To import a module, use the
- Python from statement:
-
-from com.android.monkeyrunner import <module> --
- where <module> is the class name you want to import. You can import more
- than one module in the same from statement by separating the module names with
- commas.
-
- You can either run monkeyrunner programs from a file, or enter monkeyrunner statements in
- an interactive session. You do both by invoking the monkeyrunner command
- which is found in the tools/ subdirectory of your SDK directory.
- If you provide a filename as an argument, the monkeyrunner command
- runs the file's contents as a Python program; otherwise, it starts an interactive session.
-
- The syntax of the monkeyrunner command is
-
-monkeyrunner -plugin <plugin_jar> <program_filename> <program_options> --
-Table 1 explains the flags and arguments. -
-
- Table 1. monkeyrunner flags and arguments.
| Argument | -Description | -
|---|---|
- -plugin <plugin_jar>
- |
-
- (Optional) Specifies a .jar file containing a plugin for monkeyrunner.
- To learn more about monkeyrunner plugins, see
- Extending monkeyrunner with plugins. To specify more than one
- file, include the argument multiple times.
- |
-
- <program_filename>
- |
-
- If you provide this argument, the monkeyrunner command runs the contents
- of the file as a Python program. If the argument is not provided, the command starts an
- interactive session.
- |
-
- <program_options>
- |
- - (Optional) Flags and arguments for the program in <program_file>. - | -
- You can generate an API reference for monkeyrunner by running: -
--monkeyrunner help.py <format> <outfile> --
-The arguments are: -
-<format> is either text for plain text output
- or html for HTML output.
- <outfile> is a path-qualified name for the output file.
-
- You can extend the monkeyrunner API with classes you write in the Java programming language
- and build into one or more .jar files. You can use this feature to extend the
- monkeyrunner API with your own classes or to extend the existing classes. You can also use this
- feature to initialize the monkeyrunner environment.
-
- To provide a plugin to monkeyrunner, invoke the monkeyrunner command with the
- -plugin <plugin_jar> argument described in
- table 1.
-
- In your plugin code, you can import and extend the the main monkeyrunner classes
- MonkeyDevice, MonkeyImage, and MonkeyRunner in
- com.android.monkeyrunner (see The monkeyrunner API).
-
- Note that plugins do not give you access to the Android SDK. You can't import packages
- such as com.android.app. This is because monkeyrunner interacts with the
- device or emulator below the level of the framework APIs.
-
- The .jar file for a plugin can specify a class that is instantiated before
- script processing starts. To specify this class, add the key
- MonkeyRunnerStartupRunner to the .jar file's
- manifest. The value should be the name of the class to run at startup. The following
- snippet shows how you would do this within an ant build script:
-
-<jar jarfile="myplugin" basedir="${build.dir}">
-<manifest>
-<attribute name="MonkeyRunnerStartupRunner" value="com.myapp.myplugin"/>
-</manifest>
-</jar>
-
-
-
-
- To get access to monkeyrunner's runtime environment, the startup class can implement
- com.google.common.base.Predicate<PythonInterpreter>. For example, this
- class sets up some variables in the default namespace:
-
-package com.android.example;
-
-import com.google.common.base.Predicate;
-import org.python.util.PythonInterpreter;
-
-public class Main implements Predicate<PythonInterpreter> {
- @Override
- public boolean apply(PythonInterpreter anInterpreter) {
-
- /*
- * Examples of creating and initializing variables in the monkeyrunner environment's
- * namespace. During execution, the monkeyrunner program can refer to the variables "newtest"
- * and "use_emulator"
- *
- */
- anInterpreter.set("newtest", "enabled");
- anInterpreter.set("use_emulator", 1);
-
- return true;
- }
-}
-
diff --git a/docs/html/tools/help/proguard.jd b/docs/html/tools/help/proguard.jd
deleted file mode 100755
index b38aba67b2149a4b788eebc9810591c2885b12fc..0000000000000000000000000000000000000000
--- a/docs/html/tools/help/proguard.jd
+++ /dev/null
@@ -1,493 +0,0 @@
-page.title=Shrink Your Code and Resources
-parent.title=Tools
-parent.link=index.html
-page.metaDescription=Make your APK file smaller and more secure by shrinking your code and resources.
-@jd:body
-
- To make your APK file as small as possible, you should enable shrinking for -your code and resources in your release build. This guide describes how to do -both and how to specify what to keep or discard during a build.
- -Code shrinking is available with ProGuard, which detects and removes unused -classes, fields, methods, and attributes from your packaged app, including -those from included code libraries (making it a valuable tool for working -around the 64k reference -limit). ProGuard also optimizes the bytecode, removes unused code -instructions, and obfuscates the remaining classes, fields, and methods with -short names. The obfuscated code makes your APK difficult to reverse engineer, -which is especially valuable when your app uses security-sensitive features, -such as licensing -verification.
- -Resource shrinking is available with the Android Plugin for Gradle, which -removes unused resources from your packaged app, including unused resources in -code libraries. It works in conjunction with code shrinking such that once -unused code has been removed, any resources no longer referenced can be safely -removed as well.
- - -Features in this document depend on:
-To enable code shrinking with ProGuard, add minifyEnabled true
-to the appropriate build type in your build.gradle file.
Be aware that code shrinking slows down the build time, so you should avoid -using it on your debug build if possible. However, it's important that you -do enable code shrinking on your final APK used for testing, because it might -introduce bugs if you do not sufficiently customize which -code to keep.
- -For example, the following snippet from a build.gradle file
-enables code shrinking for the release build:
-android {
- buildTypes {
- release {
- minifyEnabled true
- proguardFiles getDefaultProguardFile(‘proguard-android.txt'),
- 'proguard-rules.pro'
- }
- }
- ...
-}
-
-
-Note: Android Studio disables ProGuard when -using Instant -Run.
- -In addition to the minifyEnabled property, the
-proguardFiles property defines the ProGuard rules:
getDefaultProguardFile(‘proguard-android.txt') method gets
-the default ProGuard settings from the Android SDK tools/proguard/
-folder.
-Tip: For even more code shrinking, try the
-proguard-android-optimize.txt file that's in the same location. It
-includes the same ProGuard rules, but with other optimizations that perform
-analysis at the bytecode level—inside and across methods—to reduce your APK
-size further and help it run faster.
proguard-rules.pro file is where you can add custom
-ProGuard rules. By default, this file is located at the root of the module
-(next to the build.gradle file).To add more ProGuard rules that are specific to each build variant, add
-another proguardFiles property in the corresponding
-productFlavor block. For example, the following Gradle file adds
-flavor2-rules.pro to the flavor2 product flavor. Now
-flavor2 uses all three ProGuard rules because those from the
-release block are also applied.
-android {
- ...
- buildTypes {
- release {
- minifyEnabled true
- proguardFiles getDefaultProguardFile('proguard-android.txt'),
- 'proguard-rules.pro'
- }
- }
- productFlavors {
- flavor1 {
- }
- flavor2 {
- proguardFile 'flavor2-rules.pro'
- }
- }
-}
-
-
-With each build, ProGuard outputs the following files:
-dump.txtmapping.txtseeds.txtusage.txtThese files are saved at
-<module-name>/build/outputs/mapping/release/.
For some situations, the default ProGuard configuration file
-(proguard-android.txt) is sufficient and ProGuard removes all—and
-only—the unused code. However, many situations are difficult for ProGuard to
-analyze correctly and it might remove code your app actually needs. Some
-examples of when it might incorrectly remove code include:
AndroidManifest.xml fileTesting your app should reveal any errors caused by inappropriately removed
-code, but you can also inspect what code was removed by reviewing the
-usage.txt output file saved in
-<module-name>/build/outputs/mapping/release/.
To fix errors and force ProGuard to keep certain code, add a -keep line in the ProGuard configuration file. For example:
--keep public class MyClass -- -
Alternatively, you can add the @Keep
-annotation to the code you want to keep. Adding @Keep on a class
-keeps the entire class as-is. Adding it on a method or field will keep the
-method/field (and it's name) as well as the class name intact. Note that this
-annotation is available only when using the Annotations Support
-Library.
There are many considerations you should make when using the
--keep option; for more information about customizing your
-configuration file, read the
-ProGuard Manual. The
-Troubleshooting section outlines other common problems you might encounter
-when your code gets stripped away.
After ProGuard shrinks your code, reading a stack trace is difficult (if not
-impossible) because the method names are obfuscated. Fortunately, ProGuard
-creates a mapping.txt file each time it runs, which shows the
-original class, method, and field names mapped to the obfuscated names.
-ProGuard saves the file in the app
-<module-name>/build/outputs/mapping/release/ directory.
Be aware that the mapping.txt file is overwritten every time
-you create a release build with ProGuard, so you must carefully save a copy
-each time you publish a new release. By retaining a copy of the
-mapping.txt file for each release build, you'll be able to debug a
-problem if a user submits an obfuscated stack trace from an older version of
-your app.
When publishing your app on Google Play, you can upload the
-mapping.txt file for each version of your APK. Then Google Play
-will deobfuscate incoming stack traces from user-reported issues so you can
-review them in the Google Play Developer Console. For more information, see the
-Help Center article about how to deobfuscate
-crash stack traces.
To convert an obfuscated stack trace to a readable one yourself, use the
-retrace script (retrace.bat on Windows;
-retrace.sh on Mac/Linux). It is located in the
-<sdk-root>/tools/proguard/ directory. The script takes the
-mapping.txt file and your stack trace, producing a new, readable
-stack trace. The syntax for using the retrace tool is:
-retrace.bat|retrace.sh [-verbose] mapping.txt [<stacktrace_file>] -- -
For example:
- --retrace.bat -verbose mapping.txt obfuscated_trace.txt -- -
If you do not specify the stack trace file, the retrace tool reads from -standard input.
- -Resource shrinking works only in conjunction with code shrinking. After the -code shrinker removes all unused code, the resource shrinker can identify which -resources the app still uses. This is especially true when you add code -libraries that include resources—you must remove unused library code so the -library resources become unreferenced and, thus, removable by the resource -shrinker.
- -To enable resource shrinking, set the shrinkResources property
-to true in your build.gradle file (alongside
-minifyEnabled for code shrinking). For example:
-android {
- ...
- buildTypes {
- release {
- shrinkResources true
- minifyEnabled true
- proguardFiles getDefaultProguardFile('proguard-android.txt'),
- 'proguard-rules.pro'
- }
- }
-}
-
-
-If you haven't already built your app using minifyEnabled for
-code shrinking, then try that before enabling shrinkResources,
-because you might need to edit your proguard-rules.pro file to
-keep classes or methods that are created or invoked dynamically before you
-start removing resources.
Note: The resource shrinker currently does not
-remove resources defined in a values/ folder (such as strings,
-dimensions, styles, and colors). This is because the Android Asset Packaging
-Tool (AAPT) does not allow the Gradle Plugin to specify predefined versions for
-resources. For details, see issue 70869.
If there are specific resources you wish to keep or discard, create an XML
-file in your project with a <resources> tag and specify each
-resource to keep in the tools:keep attribute and each resource to
-discard in the tools:discard attribute. Both attributes accept a
-comma-separated list of resource names. You can use the asterisk character as a
-wild card.
For example:
- --<?xml version=1.0" encoding="utf-8"?> -<resources xmlns:tools="http://schemas.android.com/tools" - tools:keep="@layout/l_used*_c,@layout/l_used_a,@layout/l_used_b*" - tools:discard="@layout/unused2" /> -- -
Save this file in your project resources, for example, at
-res/raw/keep.xml. The build does not package this file into your
-APK.
Specifying which resources to discard might seem silly when you could
-instead delete them, but this can be useful when using build variants. For
-example, you might put all your resources into the common project directory,
-then create a different keep.xml file for each build variant when
-you know that a given resource appears to be used in code (and therefore not
-removed by the shrinker) but you know it actually won't be used for the given
-build variant.
Normally, the resource shrinker can accurately determine whether a resource -is used. However, if your code makes a call to {@link -android.content.res.Resources#getIdentifier(String,String,String) -Resources.getIdentifier()} (or if any of your libraries do that—the AppCompat -library does), that means your code is looking up resource names based on -dynamically-generated strings. When you do this, the resource shrinker behaves -defensively by default and marks all resources with a matching name format as -potentially used and unavailable for removal.
- -For example, the following code causes all resources with the
-img_ prefix to be marked as used.
-String name = String.format("img_%1d", angle + 1);
-res = getResources().getIdentifier(name, "drawable", getPackageName());
-
-
-The resource shrinker also looks through all the string constants in your
-code, as well as various res/raw/ resources, looking for resource
-URLs in a format similar to
-file:///android_res/drawable//ic_plus_anim_016.png. If it finds
-strings like this or others that look like they could be used to construct URLs
-like this, it doesn't remove them.
These are examples of the safe shrinking mode that is enabled by default.
-You can, however, turn off this "better safe than sorry" handling, and specify
-that the resource shrinker keep only resources that it's certain are used. To
-do this, set shrinkMode to strict in the
-keep.xml file, as follows:
-<?xml version="1.0" encoding="utf-8"?> -<resources xmlns:tools="http://schemas.android.com/tools" - tools:shrinkMode="strict" /> -- -
If you do enable strict shrinking mode and your code also references
-resources with dynamically-generated strings, as shown above, then you must
-manually keep those resources using the tools:keep attribute.
The Gradle resource shrinker removes only resources that are not referenced
-by your app code, which means it will not remove
-alternative resources for different device configurations. If necessary,
-you can use the Android Gradle plugin's resConfigs property to
-remove alternative resource files that your app does not need.
For example, if you are using a library that includes language resources
-(such as AppCompat or Google Play Services), then your APK includes all
-translated language strings for the messages in those libraries whether the
-rest of your app is translated to the same languages or not. If you'd like to
-keep only the languages that your app officially supports, you can specify
-those languages using the resConfig property. Any resources for
-languages not specified are removed.
The following snippet shows how to limit your language resources to just -English and French:
- -
-android {
- defaultConfig {
- ...
- resConfigs "en", "fr"
- }
-}
-
-
-To customize which screen density or ABI resources to include in your APK, -instead use APK -splits to build different APKs for different devices.
- -By default, Gradle also merges identically named resources, such as
-drawables with the same name that might be in different resource folders. This
-behavior is not controlled by the shrinkResources property and
-cannot be disabled, because it is necessary to avoid errors when multiple
-resources match the name your code is looking up.
Resource merging occurs only when two or more files share an identical -resource name, type, and qualifier. Gradle selects which file it considers to -be the best choice among the duplicates (based on a priority order described -below) and passes only that one resource to the AAPT for distribution in the -APK file.
- -Gradle looks for duplicate resources in the following locations:
- -src/main/res/.Gradle merges duplicate resources in the following cascading priority order:
- -Dependencies → Main → Build flavor → Build type
- -For example, if a duplicate resource appears in both your main resources and -a build flavor, Gradle selects the one in the build flavor.
- -If identical resources appear in the same source set, Gradle cannot merge
-them and emits a resource merge error. This can happen if you define multiple
-source sets in the sourceSet property of your
-build.gradle file—for example if both src/main/res/
-and src/main/res2/ contain identical resources.
When you shrink resources, the Gradle Console shows a summary of the -resources that it removed from the app package. For example:
- --:android:shrinkDebugResources -Removed unused resources: Binary resource data reduced from 2570KB to 1711KB: Removed 33% -:android:validateDebugSigning -- -
Gradle also creates a diagnostic file named resources.txt in
-<module-name>/build/outputs/mapping/release/ (the same
-folder as ProGuard's output files). This file includes details such as which
-resources reference other resources and which resources are used or
-removed.
For example, to find out why @drawable/ic_plus_anim_016 is
-still in your APK, open the resources.txt file and search for that
-file name. You might find that it's referenced from another resource, as
-follows:
-16:25:48.005 [QUIET] [system.out] @drawable/add_schedule_fab_icon_anim : reachable=true -16:25:48.009 [QUIET] [system.out] @drawable/ic_plus_anim_016 -- -
You now need to know why @drawable/add_schedule_fab_icon_anim
-is reachable—and if you search upwards you'll find that resource is listed
-under "The root reachable resources are:". This means there is a code reference
-to add_schedule_fab_icon_anim (that is, its R.drawable ID was
-found in the reachable code).
If you are not using strict checking, resource IDs can be marked as reachable -if there are string constants that look like they might be used to construct -resource names for dynamically loaded resources. In that case, if you search -the build output for the resource name, you might find a message like this:
- --10:32:50.590 [QUIET] [system.out] Marking drawable:ic_plus_anim_016:2130837506 - used because it format-string matches string pool constant ic_plus_anim_%1$d. -- -
If you see one of these strings and you are certain that the string is not
-being used to load the given resource dynamically, you can use the
-tools:discard attribute to inform the build system to remove it,
-as described in the section about how to customize which resources to keep.
- You can use the Android Studio File > Project Structure dialog box to - change configuration settings for your Android Studio project. This dialog - box is useful if you need to change some of the settings you chose when you - created the project. -
- -- The Project Structure dialog box contains the following sections: -
- -- The following two sections provide information on the Developer Services and Modules - sections. -
- -- The Developer Services section of the Project Structure - dialog box contains configuration pages - for several services that you can be use with your app. This section - contains the following pages: -
- -- Turning on any of these services may cause Android Studio to add necessary - dependencies and permissions to your app. Each configuration page lists these - and other actions that Android Studio takes if you enable the associated service. -
- -- The Modules settings section lets you change configuration - options for each of your project's modules. This section contains one page - for each module in your app. In many cases, the project has just a single - module, named app. However, if your project targets multiple form - factors, it might have several modules. For example, if your project contains - both a tablet app and a wearable app, it might have two modules, named - mobile and wear. For more information about project - modules, see Android Application - Modules. -
- -- Each module's settings page is divided into the following panes: -
- -The Android SDK Manager separates the SDK tools, platforms, and other components into packages -for easy access and management. You can also customize which sites the SDK Manager checks for new -or updated SDK packages and add-on tools. For example, you can configure the SDK Manager -to automatically check for updates and notify you when updates are available. -When you receive such a notification, you can then quickly decide whether to download the changes.
- -To enable automatic update checking:
-You can launch the SDK Manager in one of the following ways:
-
)
- in the menu bar. The SDK Manager appears.
-
-Figure 1. The Android SDK Manager shows the -SDK platforms and packages that are available and installed along with the SDK update sites.
- -Tip: The standalone SDK Manager is still available from the -command line, but we recommend it for use with standalone SDK installations only.
- -Click the checkbox next to -each additional SDK platform and tool that you want to install. Clear the -checkbox to uninstall an SDK platform or tool. Click Apply or OK -to update the packages and tools.
- -Tip: When an update is available for an installed
-package, a hyphen (-) appears in the checkbox next to the package. A download icon
-(
)
-also appears next
-to the checkbox to indicate the pending update. An update icon
-(
) appears next to the checkbox to
-indicate pending removals.
Click the SDK Update Sites tab to manage which SDK sites Android Studio checks for -tool and add-on updates.
- - - -There are several different packages available for the Android SDK. The following section describes -most of the available packages and where they're located in your SDK directory -after you download them.
- - - -Here's an outline of the packages required and those we recommend you use: -
- -Tip: For easy access to the SDK tools from a command line, add the
-location of the SDK tools/ and
-platform-tools to your PATH environment variable.
The previous list is not comprehensive and you can add new sites to download additional packages from third parties.
- -In some cases, an SDK package may require a specific minimum revision of -another package or SDK tool. The SDK Manager automatically notifies you of any -dependencies and downloads the required packages or tools. -In addition, development tools notify you if there are dependencies that you need to -address.
- - - -The SDK Update Sites tab displays the sites that Android Studio checks for Android SDK -and third-party updates. You can add other sites that host their own Android SDK add-ons, and then -download the SDK add-ons from those sites.
- -For example, a mobile carrier or device manufacturer might offer additional -API libraries that are supported by their own Android-powered devices. -To develop using their libraries, you must install their Android SDK add-on, if it's not already -available as a third-party add-on.
- -If a carrier or device manufacturer has hosted an SDK add-on repository file -on their website, follow these steps to add their site to the Android SDK Manager:
- -
. Any SDK packages available from the site appear in the SDK Platforms or -SDK Tools tabs.
-The Android Debug Bridge (adb) provides a Unix shell
-that you can use to run a variety of commands on an emulator or connected device. The command
-binaries are stored in the file system of the emulator or device, at /system/bin/...
-
You can use the shell command to issue commands, with or without entering
-the adb remote shell on the emulator/device. To issue a single command without entering a
-remote shell, use the shell command like this:
adb [-d|-e|-s <serialNumber>] shell <shell_command>- -
Or enter a remote shell on an emulator/device like this:
- -adb [-d|-e|-s <serialNumber>] shell- -
When you are ready to exit the remote shell, press CTRL+D or type
-exit.
Within an adb shell, you can issue commands with the activity manager ({@code am}) tool to -perform various system actions, such as start an activity, force-stop a process, -broadcast an intent, modify the device screen properties, and more. While in a shell, -the syntax is:
--am <command> -- -
You can also issue an activity manager command directly from adb -without entering a remote shell. For example:
--adb shell am start -a android.intent.action.VIEW -- - -
Table 2. Available activity manager commands
-| Command | -Description | -
|---|---|
-start [options] <INTENT>
- |
-Start an {@link android.app.Activity} specified by {@code <INTENT>}. See the -Specification for <INTENT> arguments. - Options are: -
|
-
-startservice [options] <INTENT>
- |
-Start the {@link android.app.Service} specified by {@code <INTENT>}. See the -Specification for <INTENT> arguments. - Options are: -
|
-
-force-stop <PACKAGE>
- |
-Force stop everything associated with {@code <PACKAGE>} (the app's package name). - | -
-kill [options] <PACKAGE>
- |
- Kill all processes associated with {@code <PACKAGE>}
- (the app's package name). This command kills only
- processes that are safe to kill and that will not impact the user
- experience.
- Options are: -
|
-
-kill-all
- |
-Kill all background processes. - | -
-broadcast [options] <INTENT>
- |
-Issue a broadcast intent. See the -Specification for <INTENT> arguments. - Options are: -
|
-
-instrument [options] <COMPONENT>
- |
-Start monitoring with an {@link android.app.Instrumentation} instance.
- Typically the target {@code <COMPONENT>}
- is the form {@code <TEST_PACKAGE>/<RUNNER_CLASS>}. Options are: -
|
-
-profile start <PROCESS> <FILE>
- |
-Start profiler on {@code <PROCESS>}, write results to {@code <FILE>}. - | -
-profile stop <PROCESS>
- |
-Stop profiler on {@code <PROCESS>}. - | -
-dumpheap [options] <PROCESS> <FILE>
- |
-Dump the heap of {@code <PROCESS>}, write to {@code <FILE>}. Options are: -
|
-
-set-debug-app [options] <PACKAGE>
- |
-Set application {@code <PACKAGE>} to debug. Options are: -
|
-
-clear-debug-app
- |
-Clear the package previous set for debugging with {@code set-debug-app}. - | -
-monitor [options]
- |
-Start monitoring for crashes or ANRs. Options are: -
|
-
-screen-compat [on|off] <PACKAGE>
- |
-Control screen -compatibility mode of {@code <PACKAGE>}. - | -
-display-size [reset|<WxH>]
- |
-Override emulator/device display size.
-This command is helpful for testing your app across different screen sizes by mimicking a small
-screen resolution using a device with a large screen, and vice versa.
- Example: |
-
-display-density <dpi>
- |
-Override emulator/device display density.
-This command is helpful for testing your app across different screen densities on high-density
-screen environment using a low density screen, and vice versa.
- Example: |
-
-to-uri <INTENT>
- |
-Print the given intent specification as a URI. See the -Specification for <INTENT> arguments. - |
-
-to-intent-uri <INTENT>
- |
-Print the given intent specification as an {@code intent:} URI. See the -Specification for <INTENT> arguments. - |
-
Within an adb shell, you can issue commands with the package manager ({@code pm}) tool to -perform actions and queries on application packages installed on the device. While in a shell, -the syntax is:
--pm <command> -- -
You can also issue a package manager command directly from adb -without entering a remote shell. For example:
--adb shell pm uninstall com.example.MyApp -- -
Table 3. Available package manager commands.
-| Command | -Description | -
|---|---|
-list packages [options] <FILTER>
- |
-Prints all packages, optionally only
- those whose package name contains the text in {@code <FILTER>}. Options: -
|
-
-list permission-groups
- |
-Prints all known permission groups. - | -
-list permissions [options] <GROUP>
- |
-Prints all known permissions, optionally only
- those in {@code <GROUP>}. Options: -
|
-
-list instrumentation
- |
-List all test packages. Options: -
|
-
-list features
- |
-Prints all features of the system. - | -
-list libraries
- |
-Prints all the libraries supported by the current device. - | -
-list users
- |
-Prints all users on the system. - | -
-path <PACKAGE>
- |
-Print the path to the APK of the given {@code <PACKAGE>}. - | -
-install [options] <PATH>
- |
-Installs a package (specified by {@code <PATH>}) to the system. Options: -
|
-
-uninstall [options] <PACKAGE>
- |
-Removes a package from the system. Options: -
|
-
-clear <PACKAGE>
- |
-Deletes all data associated with a package. - | -
-enable <PACKAGE_OR_COMPONENT>
- |
-Enable the given package or component (written as "package/class"). - | -
-disable <PACKAGE_OR_COMPONENT>
- |
-Disable the given package or component (written as "package/class"). - | -
-disable-user [options] <PACKAGE_OR_COMPONENT>
- |
-Options: -
|
-
-grant <PACKAGE_NAME> <PERMISSION>
- |
-Grant a permission to an app. On devices running Android 6.0 (API level 23) -and higher, may be any permission declared in the app manifest. On devices -running Android 5.1 (API level 22) and lower, must be an optional permission defined by the -app. - | -
-revoke <PACKAGE_NAME> <PERMISSION>
- |
-Revoke a permission from an app. On devices running Android 6.0 (API level -23) and higher, may be any permission declared in the app manifest. On devices -running Android 5.1 (API level 22) and lower, must be an optional permission defined by the -app. - | -
-set-install-location <LOCATION>
- |
-Changes the default install location. Location values:
-
Note: This is only intended for debugging; using this can cause - applications to break and other undesireable behavior. - |
-
-get-install-location
- |
-Returns the current install location. Return values:
-
|
-
-set-permission-enforced <PERMISSION> [true|false]
- |
-Specifies whether the given permission should be enforced. - | -
-trim-caches <DESIRED_FREE_SPACE>
- |
-Trim cache files to reach the given free space. - | -
-create-user <USER_NAME>
- |
-Create a new user with the given {@code <USER_NAME>}, - printing the new user identifier of the user. - | -
-remove-user <USER_ID>
- |
-Remove the user with the given {@code <USER_IDENTIFIER>}, - deleting all data associated with that user - | -
-get-max-users
- |
-Prints the maximum number of users supported by the device. - | -
The {@code screencap} command is a shell utility for taking a screenshot of a device display. -While in a shell, the syntax is: -
- --screencap <filename> -- - -
To use the {@code screencap} from the command line, type the following: - -
-$ adb shell screencap /sdcard/screen.png -- -
Here's an example screenshot session, using the adb shell to capture the screenshot and the -{@code pull} command to download the file from the device:
- -
-$ adb shell -shell@ $ screencap /sdcard/screen.png -shell@ $ exit -$ adb pull /sdcard/screen.png -- - -
The {@code screenrecord} command is a shell utility for recording the display of devices - running Android 4.4 (API level 19) and higher. The utility records screen activity to an MPEG-4 - file.
- -Note: Audio is not recorded with the video file.
- -A developer can use this file to create promotional or training videos. While in a shell, the syntax is:
- --screenrecord [options] <filename> -- -
To use {@code screenrecord} from the command line, type the following: - -
-$ adb shell screenrecord /sdcard/demo.mp4 -- -
Stop the screen recording by pressing Ctrl-C, otherwise the recording stops automatically -at three minutes or the time limit set by {@code --time-limit}.
- -To begin recording your device screen, run the {@code screenrecord} command to record -the video. Then, run the {@code pull} command to download the video from the device to the host -computer. Here's an example recording session:
- -
-$ adb shell -shell@ $ screenrecord --verbose /sdcard/demo.mp4 -(press Ctrl-C to stop) -shell@ $ exit -$ adb pull /sdcard/demo.mp4 -- -
The {@code screenrecord} utility can record at any supported resolution and bit rate you - request, while retaining the aspect ratio of the device display. The utility records at the native - display resolution and orientation by default, with a maximum length of three minutes.
- -There are some known limitations of the {@code screenrecord} utility that you should be aware - of when using it:
- -Table 4. {@code screenrecord} options
- -| Options | -Description | -
|---|---|
--help
- |
- Displays command syntax and options | -
- --size <WIDTHxHEIGHT>
- |
- Sets the video size: {@code 1280x720}. The default value is the device's native - display resolution (if supported), 1280x720 if not. For best results, use a size supported - by your device's Advanced Video Coding (AVC) encoder. | -
--bit-rate <RATE> |
- Sets the video bit rate for the video, in megabits per second. The default value is 4Mbps.
- You can increase the bit rate to improve video quality, but doing so results in larger movie
- files. The following example sets the recording bit rate to 6Mbps:
- screenrecord --bit-rate 6000000 /sdcard/demo.mp4- |
-
--time-limit <TIME> |
- Sets the maximum recording time, in seconds. The default and maximum value is 180 - (3 minutes). | -
--rotate |
- Rotates the output 90 degrees. This feature is experimental. | -
--verbose |
- Displays log information on the command-line screen. If you do not set this option, - the utility does not display any information while running. | -
For a list of all the available shell programs, use the following command:
- -adb shell ls /system/bin- -
Help is available for most of the commands.
- -Table 5 lists some of the more common adb shell commands.
- -Table 5. Some other adb shell commands
-| Shell Command | -Description | -Comments | -
|---|---|---|
dumpsys |
-Dumps system data to the screen. | -The Dalvik Debug Monitor Server -(DDMS) tool offers an integrated debug environment that you may find easier to use. - | -
dumpstate |
-Dumps state to a file. | -|
logcat [option]... [filter-spec]... |
-Enables system and app logging and prints output to the screen. | -|
dmesg |
-Prints kernel debugging messages to the screen. | -|
start |
-Starts (restarts) an emulator/device instance. | -- |
stop |
-Stops execution of an emulator/device instance. | -- |
From a remote shell to your device or from your host machine, you can use the sqlite3 command-line program to manage SQLite databases
- created by Android applications. The sqlite3 tool includes many useful commands,
- such as .dump to print out the contents of a table and .schema to print
- the SQL CREATE statement for an existing table. The tool also gives you the ability to execute
- SQLite commands on the fly.
To use sqlite3 from a remote shell:
adb [-d|-e|-s {<serialNumber>}] shell
- sqlite3 tool by entering the following command:
- sqlite3- -
You can also optionally specify a full path to a database that you want to explore.
- Emulator/device instances store SQLite3 databases in the directory
- /data/data/<package_name>/databases/.
sqlite3, you can issue sqlite3 commands in the
- shell. To exit and return to the adb remote shell, enter exit or press
- CTRL+D.Here's an example:
-$ adb -s emulator-5554 shell -# sqlite3 /data/data/com.example.google.rss.rssexample/databases/rssitems.db -SQLite version 3.3.12 -Enter ".help" for instructions -.... enter commands, then quit... -# sqlite> .exit -- -
To use sqlite3 locally, instead of within a shell,
- pull the database file from the device and start {@code sqlite3}:
-adb pull <database-file-on-device> --
/tools directory, specifying the database
- file:
- -sqlite3 <database-file-on-host> --
The Systrace tool helps analyze the performance of your application by capturing and - displaying execution times of your applications processes and other Android system processes. The - tool combines data from the Android kernel such as the CPU scheduler, disk activity, and - application threads to generate an HTML report that shows an overall picture of an Android - device’s system processes for a given period of time.
- -The Systrace tool is particularly useful in diagnosing display problems where an - application is slow to draw or stutters while displaying motion or animation. For more information - on how to use Systrace, see Analyzing - UI Performance with Systrace.
- -In order to run Systrace, you must have Android SDK Tools 20 or later installed. You must also -have Python installed and included in your development -computer's execution path. In order to generate a trace, you must connect a device running Android -4.1 (API Level 16) or higher to your development system using a -USB debugging connection.
- -The Systrace tool can be run either from one of the Android SDK's graphical user interface -tools, or from the command line. The following sections describe how to run the tool using either -of these methods.
- - -The Systrace tool can be run from -Android Studio -or the Android Device Monitor. - -
To run the Systrace capture user interface:
- -
at the top of the Devices panel to configure tracing. at the top of the Devices panel to configure tracing.The Systrace tool has different command line options for devices running Android 4.3 (API -level 18) and higher versus devices running Android 4.2 (API level 17) and lower. The following -sections describe the different command line options for each version.
- -The general syntax for running Systrace from the command line is as follows.
- --$ python systrace.py [options] [category1] [category2] ... [categoryN] -- -
See the sections below for example Systrace sessions.
- - -When you use Systrace on devices running Android 4.3 and higher, you can omit trace category tags -to get the defaults, or you may manually specify tags for inclusion. Here is an example execution -run that sets trace tags and generates a trace from a connected device.
- --$ cd android-sdk/platform-tools/systrace -$ python systrace.py --time=10 -o mynewtrace.html sched gfx view wm -- -
- Tip: If you want to see the names of tasks in the trace output, you must - include the {@code sched} category in your command parameters. -
- -The table below lists the Systrace command line options for devices running Android 4.3 -(API level 18) and higher.
- -| Option | - -Description | -
|---|---|
-h, --help |
-
- Show the help message. | -
-o <FILE> |
-
- Write the HTML trace report to the specified file. | -
-t N, --time=N |
-
- Trace activity for N seconds. The default value is 5 seconds. | -
-b N, --buf-size=N |
-
- Use a trace buffer size of N kilobytes. This option lets you limit the total size - of the data collected during a trace. | -
-k <KFUNCS> |
-
- Trace the activity of specific kernel functions, specified in a comma-separated list. | -
-l, --list-categories |
-
- List the available tracing category tags. The available tags are:
-
-
Note: Some trace categories are not supported on all - devices. - -Tip: If you want to see the names of tasks in the trace - output, you must include the {@code sched} category in your command parameters. - - |
-
-a <APP_NAME> |
-
- Enable tracing for applications, specified as a comma-separated list of - package names. - The apps must contain tracing instrumentation calls from the {@link android.os.Trace} class. - For more information, see Analyzing - UI Performance with Systrace. - | -
--from-file=<FROM_FILE> |
-
- Create the interactive Systrace report from a file, instead of running a live trace. | -
- -e <DEVICE_SERIAL> |
-
- Conduct the trace on a specific connected device, identified by its - device serial number. | -
Using Systrace on the command line with devices running Android 4.2 and lower is typically a -two-step process. You must first set the trace tags you want to capture and then run the trace. -Here is an example execution run that sets trace tags and generates a trace from a connected -device.
- --$ cd android-sdk/platform-tools/systrace -$ python systrace.py --set-tags gfx,view,wm -$ adb shell stop -$ adb shell start -$ python systrace.py --disk --time=10 -o mynewtrace.html -- -
The table below lists the Systrace command line options for devices running Android 4.2 -(API level 17) and lower.
- -| Option | - -Description | -
|---|---|
-h, --help |
-
- Show the help message. | -
-o <FILE> |
-
- Write the HTML trace report to the specified file. | -
-t N, --time=N |
-
- Trace activity for N seconds. The default value is 5 seconds. | -
-b N, --buf-size=N |
-
- Use a trace buffer size of N kilobytes. This option lets you limit the total size - of the data collected during a trace. | -
-d, --disk |
-
- Trace disk input and output activity. This option requires root access on the device. | -
-f, --cpu-freq |
-
- Trace CPU frequency changes. Only changes to the CPU frequency are logged, so the initial - frequency of the CPU when tracing starts is not shown. | -
-i, --cpu-idle |
-
- Trace CPU idle events. | -
-l, --cpu-load |
-
- Trace CPU load. This value is a percentage determined by the interactive CPU frequency - governor. | -
-s, --no-cpu-sched |
-
- Prevent tracing of the CPU scheduler. This option allows for longer trace times by reducing - the rate of data flowing into the trace buffer. | -
-u, --bus-utilization |
-
- Trace the bus utilization levels. This option requires root access on the device. | -
-w, --workqueue |
-
- Trace kernel work queues. This option requires root access on the device. | -
--set-tags=<TAGS> |
-
- Set the enabled trace tags in a comma separated list. The available tags are:
-
Note: When setting trace tags from the command line, you - must stop and restart the framework ({@code $ adb shell stop; adb shell start}) for the - tag tracing changes to take effect. - |
-
You can set the trace tags for Systrace on -your Android 4.2 and lower device by navigating to Settings > Developer options > -Monitoring > Enable traces.
- - -The table below lists the keyboard shortcuts that are available while viewing a Systrace -trace HTML report.
- -| Key | - -Description | -
|---|---|
| w | - -Zoom into the trace timeline. | -
| s | - -Zoom out of the trace timeline. | -
| a | - -Pan left on the trace timeline. | -
| d | - -Pan right on the trace timeline. | -
| e | - -Center the trace timeline on the current mouse location. | -
| g | - -Show grid at the start of the currently selected task. | -
| Shift+g | - -Show grid at the end of the currently selected task. | -
| Right Arrow | - -Select the next event on the currently selected timeline. | -
| Left Arrow | - -Select the previous event on the currently selected timeline. | -
-The Theme Editor is a visual assistant that helps you: -
--This page introduces the fundamental tasks that you can perform with the Theme -Editor, and explains how to do so. -
- - --This section describes how to access the Theme Editor, and how it is laid out. -
- -There are two ways to open the Theme Editor:
- --The Theme Editor's main screen is divided into two sections. The left side of the editor -shows what specific UI elements, such as the app bar or a raised button, look like -when you apply the current theme to them. The right side of the editor displays -the settings for the color resources, such as Theme parent and -colorPrimary, that comprise the current theme. You can modify design -themes by changing these resource settings. -
- --The Theme Editor allows you to create new themes, modify existing ones, and manage the -colors that make up the themes. -
- --To create a theme, follow these steps: -
--To rename a theme, perform the following steps: -
-To change an existing color resource, such as colorPrimary, -follow these steps: -
-You can also directly select colors from the material palette, which the editor displays -as two rows of colored squares beneath the color picker.
- --The Theme Editor allows you to preview - -colors associated with different states. To do so, open the Resource dialog, and click -the State List tab that appears at the top of the dialog.
- --To more fully control the states themselves, you can directly view and edit their -properties in the XML file, -such as {@code colors.xml}, that defines them. For more information, see the -documentation for the {@link android.content.res.ColorStateList} class. -
- --You can choose - -device-specific configurations for your app to support. Perform -the following steps to do so: -
- -For more information about the relationship -between directory names and configurations, see - -Supporting Multiple Screens. For more information about -supported directory names, see - -Providing Resources. -
- - diff --git a/docs/html/tools/help/thumbnails/am-androidmon2.png b/docs/html/tools/help/thumbnails/am-androidmon2.png deleted file mode 100644 index a4a757193b09b445054dc74d015e377d2fa47f49..0000000000000000000000000000000000000000 Binary files a/docs/html/tools/help/thumbnails/am-androidmon2.png and /dev/null differ diff --git a/docs/html/tools/help/thumbnails/am-cpumon.png b/docs/html/tools/help/thumbnails/am-cpumon.png deleted file mode 100644 index 59908c854db967ab2108f983edaf080aaec7855d..0000000000000000000000000000000000000000 Binary files a/docs/html/tools/help/thumbnails/am-cpumon.png and /dev/null differ diff --git a/docs/html/tools/help/thumbnails/am-cpumon2.png b/docs/html/tools/help/thumbnails/am-cpumon2.png deleted file mode 100644 index 6ac6e0287a0905f66fef02c9d0d48a4110dd198c..0000000000000000000000000000000000000000 Binary files a/docs/html/tools/help/thumbnails/am-cpumon2.png and /dev/null differ diff --git a/docs/html/tools/help/thumbnails/am-gc2.png b/docs/html/tools/help/thumbnails/am-gc2.png deleted file mode 100644 index a5e8b6e986d4fad6cfe938f547e71489991580e0..0000000000000000000000000000000000000000 Binary files a/docs/html/tools/help/thumbnails/am-gc2.png and /dev/null differ diff --git a/docs/html/tools/help/thumbnails/am-gpumon.png b/docs/html/tools/help/thumbnails/am-gpumon.png deleted file mode 100644 index a414fe5e45fb8b32e1ec3d00d40f03367215c0fa..0000000000000000000000000000000000000000 Binary files a/docs/html/tools/help/thumbnails/am-gpumon.png and /dev/null differ diff --git a/docs/html/tools/help/thumbnails/am-gpumon2.png b/docs/html/tools/help/thumbnails/am-gpumon2.png deleted file mode 100644 index 5cf51d9320b298b41b5915a44ad38d4fec288c4e..0000000000000000000000000000000000000000 Binary files a/docs/html/tools/help/thumbnails/am-gpumon2.png and /dev/null differ diff --git a/docs/html/tools/help/thumbnails/am-logcatmon2.png b/docs/html/tools/help/thumbnails/am-logcatmon2.png deleted file mode 100644 index 563593568f1773919ce83547279da15a47980b93..0000000000000000000000000000000000000000 Binary files a/docs/html/tools/help/thumbnails/am-logcatmon2.png and /dev/null differ diff --git a/docs/html/tools/help/thumbnails/am-memorymon.png b/docs/html/tools/help/thumbnails/am-memorymon.png deleted file mode 100644 index 0fefb27cd5531d6ff1e903c15ee5825b230ebc96..0000000000000000000000000000000000000000 Binary files a/docs/html/tools/help/thumbnails/am-memorymon.png and /dev/null differ diff --git a/docs/html/tools/help/thumbnails/am-networkmon.png b/docs/html/tools/help/thumbnails/am-networkmon.png deleted file mode 100644 index db9c647b7f0c9457606eab0d85aa31cf3c0aa5a8..0000000000000000000000000000000000000000 Binary files a/docs/html/tools/help/thumbnails/am-networkmon.png and /dev/null differ diff --git a/docs/html/tools/help/thumbnails/am_alloctracker.png b/docs/html/tools/help/thumbnails/am_alloctracker.png deleted file mode 100644 index b94713d3cc284dd6f28d9e8da8062d43497ca68e..0000000000000000000000000000000000000000 Binary files a/docs/html/tools/help/thumbnails/am_alloctracker.png and /dev/null differ diff --git a/docs/html/tools/help/thumbnails/am_androidmon.png b/docs/html/tools/help/thumbnails/am_androidmon.png deleted file mode 100644 index 6b0523019b19870a1af128ffbd89ca881f5fc847..0000000000000000000000000000000000000000 Binary files a/docs/html/tools/help/thumbnails/am_androidmon.png and /dev/null differ diff --git a/docs/html/tools/help/thumbnails/am_cpumon.png b/docs/html/tools/help/thumbnails/am_cpumon.png deleted file mode 100644 index c8c0415535d183d5e3af0d8e1f00307fe6e9c882..0000000000000000000000000000000000000000 Binary files a/docs/html/tools/help/thumbnails/am_cpumon.png and /dev/null differ diff --git a/docs/html/tools/help/thumbnails/am_gpumon.png b/docs/html/tools/help/thumbnails/am_gpumon.png deleted file mode 100644 index e453e7de63c6cf05006ad65e58006326d294ff48..0000000000000000000000000000000000000000 Binary files a/docs/html/tools/help/thumbnails/am_gpumon.png and /dev/null differ diff --git a/docs/html/tools/help/thumbnails/am_hprofviewer.png b/docs/html/tools/help/thumbnails/am_hprofviewer.png deleted file mode 100644 index 342590fd41b2c20ef52793016b5597ca6b4cf65a..0000000000000000000000000000000000000000 Binary files a/docs/html/tools/help/thumbnails/am_hprofviewer.png and /dev/null differ diff --git a/docs/html/tools/help/thumbnails/am_iscreencapture.png b/docs/html/tools/help/thumbnails/am_iscreencapture.png deleted file mode 100644 index 68135a711a74312fb29825e2d3e8de1a6d43c3d5..0000000000000000000000000000000000000000 Binary files a/docs/html/tools/help/thumbnails/am_iscreencapture.png and /dev/null differ diff --git a/docs/html/tools/help/thumbnails/am_isysteminfo.png b/docs/html/tools/help/thumbnails/am_isysteminfo.png deleted file mode 100644 index 37d77db9c036c0b955febe83512c7d8d81555747..0000000000000000000000000000000000000000 Binary files a/docs/html/tools/help/thumbnails/am_isysteminfo.png and /dev/null differ diff --git a/docs/html/tools/help/thumbnails/am_ivideo.png b/docs/html/tools/help/thumbnails/am_ivideo.png deleted file mode 100644 index 901eaf14002145b46c73d6433b29d4bbae4e08db..0000000000000000000000000000000000000000 Binary files a/docs/html/tools/help/thumbnails/am_ivideo.png and /dev/null differ diff --git a/docs/html/tools/help/thumbnails/am_logcatmon.png b/docs/html/tools/help/thumbnails/am_logcatmon.png deleted file mode 100644 index ca7063cb0ba0554c41da161890912a342ef5ad9f..0000000000000000000000000000000000000000 Binary files a/docs/html/tools/help/thumbnails/am_logcatmon.png and /dev/null differ diff --git a/docs/html/tools/help/thumbnails/am_methodtrace.png b/docs/html/tools/help/thumbnails/am_methodtrace.png deleted file mode 100644 index 8d5ca4e6089ef8ac0bb1018c1b68573b0b3897a1..0000000000000000000000000000000000000000 Binary files a/docs/html/tools/help/thumbnails/am_methodtrace.png and /dev/null differ diff --git a/docs/html/tools/help/thumbnails/am_networkmon2.png b/docs/html/tools/help/thumbnails/am_networkmon2.png deleted file mode 100644 index f55f853e51afd16fd267ae97ec4eee96e2a4a6a0..0000000000000000000000000000000000000000 Binary files a/docs/html/tools/help/thumbnails/am_networkmon2.png and /dev/null differ diff --git a/docs/html/tools/help/thumbnails/am_screenshot.png b/docs/html/tools/help/thumbnails/am_screenshot.png deleted file mode 100644 index 66afff91facbdb7b21d1b84f316ea2d82d2ede44..0000000000000000000000000000000000000000 Binary files a/docs/html/tools/help/thumbnails/am_screenshot.png and /dev/null differ diff --git a/docs/html/tools/help/thumbnails/am_sysinfo.png b/docs/html/tools/help/thumbnails/am_sysinfo.png deleted file mode 100644 index 9b5cd17207fb4d84c1293518f724d0c25d71a08b..0000000000000000000000000000000000000000 Binary files a/docs/html/tools/help/thumbnails/am_sysinfo.png and /dev/null differ diff --git a/docs/html/tools/help/thumbnails/am_video.png b/docs/html/tools/help/thumbnails/am_video.png deleted file mode 100644 index 209cb0c7d10d31012a42a4f025644a24e75f5b22..0000000000000000000000000000000000000000 Binary files a/docs/html/tools/help/thumbnails/am_video.png and /dev/null differ diff --git a/docs/html/tools/help/traceview.jd b/docs/html/tools/help/traceview.jd deleted file mode 100644 index a26829132760aaa8122f9ff9b638a7c8cf0cb949..0000000000000000000000000000000000000000 --- a/docs/html/tools/help/traceview.jd +++ /dev/null @@ -1,28 +0,0 @@ -page.title=Traceview -parent.title=Tools -parent.link=index.html -@jd:body - -Traceview is a graphical viewer for execution logs saved by your application. -Traceview can help you debug your application and profile its performance.
- -To start the Traceview tool:
- -For more information on how to use Traceview, see -Profiling with Traceview and -dmtracedump. -
- -Note: Running traceview from the command line
-has been deprecated.
-If your application supports multiple languages, you need to properly manage your -translated string resources. Android Studio provides the Translations Editor to make viewing and -managing your translated resources easier. -
- --Translated resources are stored in multiple XML files in multiple directories in your project. -Manually finding and editing resource files across many translations can be difficult. Because of -this, your application might have missing translations that go unnoticed until after your -application has been built and distributed to users. -
- --The Translations Editor lets you view and update all your string resources in one convenient -place. The editor gives you a single view of all of your translated resources, making it easy to -change or add translations, and even find missing translations. -
- -
-Figure 1. Manage locales and strings in the -Translations Editor.
- --Follow these steps to start the Translations Editor: -
- -
Using Android Studiostrings.xml file (not folder) and select Open
- Translations Editor.
-You can also access the Translations Editor by opening a strings.xml file for editing
-and clicking the Open editor link, or clicking the globe icon
-
in the Design layout view and
-choosing Edit Translations.
-
-The Translations Editor provides a view of all your string resources and current locale -translations. The name of each resource is listed in the Key column, along with a default value -for the key, a checkbox to mark the key as untranslatable, and values for each locale translation. -
- --Edit translations by double-clicking on the translation and editing the value directly -in the list view, or selecting the translation and editing the Translation field -value at the bottom of the editor. The default value can be edited by double-clicking on -the default value or selecting the default value and updating the Default Value -field.
- --If a resource is missing a translation and isn't marked untranslatable, the key name is -displayed in red. If you hover over a red resource, Android Studio displays details about the -missing translations. -
- -
-Add a new resource by clicking the add icon 
. Android Studio prompts you for a key name,
-default value, and resource folder that contains the strings.xml file where the new
-resource is added.
-
-Add additional locales by pressing the globe icon
- and selecting the locale you want
-to add. The Translations Editor adds the new locale column and creates the translation strings XML
-file in the appropriate project directory.
-
-The Translations Editor has -BCP 47 support, and -combines language and region codes into a single selection for targeted localizations. -
- --Clicking the Order a translation link opens a page in your browser where you -can upload string resource XML files and order translation services. App translation services are -available from Google Play and other vendors. For more information about Google Play App -Translation Services, see the -Google Play App Translation Service announcement. -
- diff --git a/docs/html/tools/help/uiautomator/Configurator.jd b/docs/html/tools/help/uiautomator/Configurator.jd deleted file mode 100644 index b6e15f65eb1541e20879c154098791ccb2038c5c..0000000000000000000000000000000000000000 --- a/docs/html/tools/help/uiautomator/Configurator.jd +++ /dev/null @@ -1,960 +0,0 @@ -page.title=Configurator -parent.title=uiautomator -parent.link=index.html - -@jd:body - - -Allows you to set key parameters for running uiautomator tests. The new
-settings take effect immediately and can be changed any time during a test run.
-To modify parameters using Configurator, first
-obtain an instance by calling getInstance().
-As a best practice, make sure you always save the original value of any
-parameter that you are modifying. After running your tests with the modified
-parameters, make sure to also restore the original parameter values, otherwise
-this will impact other tests cases.
| Public Methods | |||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
Gets the current timeout for waiting for an acknowledgment of generic
- uiautomator actions, such as clicks, text setting, and menu presses.
-
- | |||||||||||
Retrieves a singleton instance of Configurator.
-
- | |||||||||||
Gets the current delay between key presses when injecting text input.
-
- | |||||||||||
Gets the timeout for waiting for an acknowledgement of an
- uiautomtor scroll swipe action.
-
- | |||||||||||
Gets the current timeout used for waiting for the user interface to go
- into an idle state.
-
- | |||||||||||
Gets the current timeout for waiting for a widget to become visible in
- the user interface so that it can be matched by a selector.
-
- | |||||||||||
Sets the timeout for waiting for an acknowledgment of generic uiautomator
- actions, such as clicks, text setting, and menu presses.
-
- | |||||||||||
Sets a delay between key presses when injecting text input.
-
- | |||||||||||
Sets the timeout for waiting for an acknowledgement of an
- uiautomtor scroll swipe action.
-
- | |||||||||||
Sets the timeout for waiting for the user interface to go into an idle
- state before starting a uiautomator action.
-
- | |||||||||||
Sets the timeout for waiting for a widget to become visible in the user
- interface so that it can be matched by a selector.
-
- | |||||||||||
|
- [Expand]
- Inherited Methods | |||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
- 
-From class
-
- java.lang.Object
-
-
-
-
-
-
- | |||||||||||
Gets the current timeout for waiting for an acknowledgment of generic
- uiautomator actions, such as clicks, text setting, and menu presses.
-
- The acknowledgment is an AccessibilityEvent,
- corresponding to an action, that lets the framework determine if the
- action was successful. Generally, this timeout should not be modified.
- See UiObject
Retrieves a singleton instance of Configurator.
Gets the current delay between key presses when injecting text input.
- See setText(String)
Gets the timeout for waiting for an acknowledgement of an
- uiautomtor scroll swipe action.
-
- The acknowledgment is an AccessibilityEvent,
- corresponding to the scroll action, that lets the framework determine if
- the scroll action was successful. Generally, this timeout should not be modified.
- See UiScrollable
Gets the current timeout used for waiting for the user interface to go
- into an idle state.
-
- By default, all core uiautomator objects except UiDevice will perform
- this wait before starting to search for the widget specified by the
- object's UiSelector. Once the idle state is detected or the
- timeout elapses (whichever occurs first), the object will start to wait
- for the selector to find a match.
- See setWaitForSelectorTimeout(long)
Gets the current timeout for waiting for a widget to become visible in - the user interface so that it can be matched by a selector. - - Because user interface content is dynamic, sometimes a widget may not - be visible immediately and won't be detected by a selector. This timeout - allows the uiautomator framework to wait for a match to be found, up until - the timeout elapses.
Sets the timeout for waiting for an acknowledgment of generic uiautomator
- actions, such as clicks, text setting, and menu presses.
-
- The acknowledgment is an AccessibilityEvent,
- corresponding to an action, that lets the framework determine if the
- action was successful. Generally, this timeout should not be modified.
- See UiObject
| timeout - | Timeout value in milliseconds | -
|---|
Sets a delay between key presses when injecting text input.
- See setText(String)
| delay - | Delay value in milliseconds | -
|---|
Sets the timeout for waiting for an acknowledgement of an
- uiautomtor scroll swipe action.
-
- The acknowledgment is an AccessibilityEvent,
- corresponding to the scroll action, that lets the framework determine if
- the scroll action was successful. Generally, this timeout should not be modified.
- See UiScrollable
| timeout - | Timeout value in milliseconds | -
|---|
Sets the timeout for waiting for the user interface to go into an idle
- state before starting a uiautomator action.
-
- By default, all core uiautomator objects except UiDevice will perform
- this wait before starting to search for the widget specified by the
- object's UiSelector. Once the idle state is detected or the
- timeout elapses (whichever occurs first), the object will start to wait
- for the selector to find a match.
- See setWaitForSelectorTimeout(long)
| timeout - | Timeout value in milliseconds | -
|---|
Sets the timeout for waiting for a widget to become visible in the user - interface so that it can be matched by a selector. - - Because user interface content is dynamic, sometimes a widget may not - be visible immediately and won't be detected by a selector. This timeout - allows the uiautomator framework to wait for a match to be found, up until - the timeout elapses.
| timeout - | Timeout value in milliseconds. | -
|---|
Provides auxiliary support for running test cases - -
- -| Public Methods | |||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
| - abstract - - - - - void - | -
- sendStatus(int resultCode, Bundle status)
-
- Allows the running test cases to send out interim status
-
- | ||||||||||
Allows the running test cases to send out interim status
UI automation tests should extend this class. This class provides access - to the following: -
UiDevice instance| Public Constructors | |||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
| - - - - - - - | -- UiAutomatorTestCase() - - | ||||||||||
| Public Methods | |||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
| - - - - - - IAutomationSupport - | -
- getAutomationSupport()
-
- Provides support for running tests to report interim status
-
- | ||||||||||
| - - - - - - Bundle - | -
- getParams()
-
- Get command line parameters.
-
- | ||||||||||
| - - - - - - UiDevice - | -
- getUiDevice()
-
- Get current instance of
-
- UiDevice. | ||||||||||
| - - - - - - void - | -
- sleep(long ms)
-
- Calls
-
- sleep(long) to sleep | ||||||||||
|
- [Expand]
- Inherited Methods | |||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
|
-
-From class
-
- junit.framework.TestCase
-
-
-
-
-
-
- | |||||||||||
|
-
-From class
-
- junit.framework.Assert
-
-
-
-
-
-
- | |||||||||||
|
-
-From class
-
- java.lang.Object
-
-
-
-
-
-
- | |||||||||||
|
-
-From interface
-
- junit.framework.Test
-
-
-
-
-
-
- | |||||||||||
Provides support for running tests to report interim status
Get command line parameters. On the command line when passing -e key value
- pairs, the Bundle will have the key value pairs conveniently available to the
- tests.
-
Get current instance of UiDevice. Works similar to calling the static
- getInstance() from anywhere in the test classes.
-
Calls sleep(long) to sleep
| ms | -is in milliseconds. - | -
|---|
Used to enumerate a container's user interface (UI) elements for the purpose of counting, - or targeting a sub elements by a child's text or description. -
- - -| Public Constructors | |||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
| - - - - - - - | -- UiCollection(UiSelector selector) - - | ||||||||||
| Public Methods | |||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
| - - - - - - UiObject - | -
- getChildByDescription(UiSelector childPattern, String text)
-
- Searches for child UI element within the constraints of this
-
- UiSelector
- selector. | ||||||||||
| - - - - - - UiObject - | -
- getChildByInstance(UiSelector childPattern, int instance)
-
- Searches for child UI element within the constraints of this
-
- UiSelector. | ||||||||||
| - - - - - - UiObject - | -
- getChildByText(UiSelector childPattern, String text)
-
- Searches for child UI element within the constraints of this
-
- UiSelector. | ||||||||||
| - - - - - - int - | -
- getChildCount(UiSelector childPattern)
-
- Counts child UI element instances matching the
-
- childPattern
- argument. | ||||||||||
|
- [Expand]
- Inherited Methods | |||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
|
-
-From class
-
- com.android.uiautomator.core.UiObject
-
-
-
-
-
-
- | |||||||||||
|
-
-From class
-
- java.lang.Object
-
-
-
-
-
-
- | |||||||||||
Searches for child UI element within the constraints of this UiSelector
- selector.
-
- It looks for any child matching the childPattern argument that has
- a child UI element anywhere within its sub hierarchy that has content-description text.
- The returned UiObject will point at the childPattern instance that matched the
- search and not at the identifying child element that matched the content description.
| childPattern | -UiSelector selector of the child pattern to match and return |
-
|---|---|
| text | -String of the identifying child contents of of the childPattern |
-
UiObject pointing at and instance of childPattern| UiObjectNotFoundException - | - |
|---|
Searches for child UI element within the constraints of this UiSelector.
-
- It looks for any child matching the childPattern argument that has
- a child UI element anywhere within its sub hierarchy that is at the instance
- specified. The operation is performed only on the visible items and no scrolling is performed
- in this case.
| childPattern | -UiSelector selector of the child pattern to match and return |
-
|---|---|
| instance | -int the desired matched instance of this childPattern |
-
UiObject pointing at and instance of childPattern
-| UiObjectNotFoundException - | - |
|---|
Searches for child UI element within the constraints of this UiSelector
- selector.
-
- It looks for any child matching the childPattern argument that has
- a child UI element anywhere within its sub hierarchy that has a text attribute equal to
- text. The returned UiObject will point at the childPattern
- instance that matched the search and not at the identifying child element that matched the
- text attribute.
| childPattern | -UiSelector selector of the child pattern to match and return |
-
|---|---|
| text | -String of the identifying child contents of of the childPattern |
-
UiObject pointing at and instance of childPattern| UiObjectNotFoundException - | - |
|---|
Counts child UI element instances matching the childPattern
- argument. The method returns the number of matching UI elements that are
- currently visible. The count does not include items of a scrollable list
- that are off-screen.
| childPattern | -a UiSelector that represents the matching child UI
- elements to count |
-
|---|
UiCollection
-Provides access to state information about the device. You can -also use this class to simulate user actions on the device, such as pressing -the d-pad or pressing the Home and Menu buttons.
- -| Public Methods | |||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
Clears the text from the last UI traversal event.
-
- | |||||||||||
Perform a click at arbitrary coordinates specified by the user
-
- | |||||||||||
Performs a swipe from one coordinate to another coordinate.
-
- | |||||||||||
Helper method used for debugging to dump the current window's layout hierarchy.
-
- | |||||||||||
Disables the sensors and freezes the device rotation at its
- current rotation state.
-
- | |||||||||||
- This method is deprecated.
- The results returned should be considered unreliable
-
- | |||||||||||
Retrieves the name of the last package to report accessibility events.
-
- | |||||||||||
Gets the height of the display, in pixels.
-
- | |||||||||||
Returns the current rotation of the display, as defined in
-
- Surface | |||||||||||
Returns the display size in dp (device-independent pixel)
-
- The returned display size is adjusted per screen rotation.
-
- | |||||||||||
Gets the width of the display, in pixels.
-
- | |||||||||||
Retrieves a singleton instance of UiDevice
-
- | |||||||||||
Retrieves the text from the last UI traversal event received.
-
- | |||||||||||
Retrieves the product name of the device.
-
- | |||||||||||
Checks if any registered
-
- UiWatcher have triggered. | |||||||||||
Checks if a specific registered
-
- UiWatcher has triggered. | |||||||||||
Check if the device is in its natural orientation.
-
- | |||||||||||
Checks the power manager if the screen is ON.
-
- | |||||||||||
Opens the notification shade.
-
- | |||||||||||
Opens the Quick Settings shade.
-
- | |||||||||||
Simulates a short press on the BACK button.
-
- | |||||||||||
Simulates a short press on the CENTER button.
-
- | |||||||||||
Simulates a short press on the DOWN button.
-
- | |||||||||||
Simulates a short press on the LEFT button.
-
- | |||||||||||
Simulates a short press on the RIGHT button.
-
- | |||||||||||
Simulates a short press on the UP button.
-
- | |||||||||||
Simulates a short press on the DELETE key.
-
- | |||||||||||
Simulates a short press on the ENTER key.
-
- | |||||||||||
Simulates a short press on the HOME button.
-
- | |||||||||||
Simulates a short press using a key code.
-
- | |||||||||||
Simulates a short press using a key code.
-
- | |||||||||||
Simulates a short press on the MENU button.
-
- | |||||||||||
Simulates a short press on the Recent Apps button.
-
- | |||||||||||
Simulates a short press on the SEARCH button.
-
- | |||||||||||
Registers a
-
- UiWatcher to run automatically when the testing framework is unable to
- find a match using a UiSelector. | |||||||||||
Removes a previously registered
-
- UiWatcher. | |||||||||||
Resets a
-
- UiWatcher that has been triggered. | |||||||||||
This method forces all registered watchers to run.
-
- | |||||||||||
Enables or disables layout hierarchy compression.
-
- | |||||||||||
Simulates orienting the device to the left and also freezes rotation
- by disabling the sensors.
-
- | |||||||||||
Simulates orienting the device into its natural orientation and also freezes rotation
- by disabling the sensors.
-
- | |||||||||||
Simulates orienting the device to the right and also freezes rotation
- by disabling the sensors.
-
- | |||||||||||
This method simply presses the power button if the screen is ON else
- it does nothing if the screen is already OFF.
-
- | |||||||||||
Performs a swipe between points in the Point array.
-
- | |||||||||||
Performs a swipe from one coordinate to another using the number of steps
- to determine smoothness and speed.
-
- | |||||||||||
Take a screenshot of current window and store it as PNG
-
- Default scale of 1.0f (original size) and 90% quality is used
- The screenshot is adjusted per screen rotation
-
- | |||||||||||
Take a screenshot of current window and store it as PNG
-
- The screenshot is adjusted per screen rotation
-
- | |||||||||||
Re-enables the sensors and un-freezes the device rotation allowing its contents
- to rotate with the device physical rotation.
-
- | |||||||||||
Waits for the current application to idle.
-
- | |||||||||||
Waits for the current application to idle.
-
- | |||||||||||
Waits for a window content update event to occur.
-
- | |||||||||||
This method simulates pressing the power button if the screen is OFF else
- it does nothing if the screen is already ON.
-
- | |||||||||||
|
- [Expand]
- Inherited Methods | |||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
|
-
-From class
-
- java.lang.Object
-
-
-
-
-
-
- | |||||||||||
Clears the text from the last UI traversal event.
- See getLastTraversedText().
Perform a click at arbitrary coordinates specified by the user
| x - | coordinate | -
|---|---|
| y - | coordinate | -
Performs a swipe from one coordinate to another coordinate. You can control - the smoothness and speed of the swipe by specifying the number of steps. - Each step execution is throttled to 5 milliseconds per step, so for a 100 - steps, the swipe will take around 0.5 seconds to complete.
| startX - | X-axis value for the starting coordinate | -
|---|---|
| startY - | Y-axis value for the starting coordinate | -
| endX - | X-axis value for the ending coordinate | -
| endY - | Y-axis value for the ending coordinate | -
| steps - | is the number of steps for the swipe action | -
Helper method used for debugging to dump the current window's layout hierarchy. - The file root location is /data/local/tmp
Disables the sensors and freezes the device rotation at its - current rotation state.
| - | RemoteException | -
|---|---|
| RemoteException - | - |
-
- This method is deprecated.
- The results returned should be considered unreliable
-
Retrieves the last activity to report accessibility events.
Retrieves the name of the last package to report accessibility events.
Gets the height of the display, in pixels. The size is adjusted based - on the current orientation of the display.
Returns the current rotation of the display, as defined in Surface
Returns the display size in dp (device-independent pixel) - - The returned display size is adjusted per screen rotation. Also this will return the actual - size of the screen, rather than adjusted per system decorations (like status bar).
Gets the width of the display, in pixels. The width and height details - are reported based on the current orientation of the display.
Retrieves a singleton instance of UiDevice
Retrieves the text from the last UI traversal event received. - - You can use this method to read the contents in a WebView container - because the accessibility framework fires events - as each text is highlighted. You can write a test to perform - directional arrow presses to focus on different elements inside a WebView, - and call this method to get the text from each traversed element. - If you are testing a view container that can return a reference to a - Document Object Model (DOM) object, your test should use the view's - DOM instead.
Retrieves the product name of the device. - - This method provides information on what type of device the test is running on. This value is - the same as returned by invoking #adb shell getprop ro.product.name.
Checks if any registered UiWatcher have triggered.
-
- See registerWatcher(String, UiWatcher)
- See hasWatcherTriggered(String)
Checks if a specific registered UiWatcher has triggered.
- See registerWatcher(String, UiWatcher). If a UiWatcher runs and its
- checkForCondition() call returned true, then
- the UiWatcher is considered triggered. This is helpful if a watcher is detecting errors
- from ANR or crash dialogs and the test needs to know if a UiWatcher has been triggered.
Check if the device is in its natural orientation. This is determined by checking if the - orientation is at 0 or 180 degrees.
Checks the power manager if the screen is ON.
| - | RemoteException | -
|---|---|
| RemoteException - | - |
Opens the notification shade.
Opens the Quick Settings shade.
Simulates a short press on the BACK button.
Simulates a short press on the CENTER button.
Simulates a short press on the DOWN button.
Simulates a short press on the LEFT button.
Simulates a short press on the RIGHT button.
Simulates a short press on the UP button.
Simulates a short press on the DELETE key.
Simulates a short press on the ENTER key.
Simulates a short press on the HOME button.
Simulates a short press using a key code.
-
- See KeyEvent.
| keyCode - | the key code of the event. | -
|---|---|
| metaState - | an integer in which each bit set to 1 represents a pressed meta key | -
Simulates a short press using a key code.
-
- See KeyEvent
Simulates a short press on the MENU button.
Simulates a short press on the Recent Apps button.
| - | RemoteException | -
|---|---|
| RemoteException - | - |
Simulates a short press on the SEARCH button.
Registers a UiWatcher to run automatically when the testing framework is unable to
- find a match using a UiSelector. See runWatchers()
| name - | to register the UiWatcher | -
|---|---|
| watcher - | UiWatcher |
-
Removes a previously registered UiWatcher.
-
- See registerWatcher(String, UiWatcher)
| name - | used to register the UiWatcher | -
|---|
Resets a UiWatcher that has been triggered.
- If a UiWatcher runs and its checkForCondition() call
- returned true, then the UiWatcher is considered triggered.
- See registerWatcher(String, UiWatcher)
This method forces all registered watchers to run.
- See registerWatcher(String, UiWatcher)
Enables or disables layout hierarchy compression. - - If compression is enabled, the layout hierarchy derived from the Acessibility - framework will only contain nodes that are important for uiautomator - testing. Any unnecessary surrounding layout nodes that make viewing - and searching the hierarchy inefficient are removed.
| compressed - | true to enable compression; else, false to disable | -
|---|
Simulates orienting the device to the left and also freezes rotation
- by disabling the sensors.
-
- If you want to un-freeze the rotation and re-enable the sensors
- see unfreezeRotation().
| - | RemoteException | -
|---|---|
| RemoteException - | - |
Simulates orienting the device into its natural orientation and also freezes rotation
- by disabling the sensors.
-
- If you want to un-freeze the rotation and re-enable the sensors
- see unfreezeRotation().
| - | RemoteException | -
|---|---|
| RemoteException - | - |
Simulates orienting the device to the right and also freezes rotation
- by disabling the sensors.
-
- If you want to un-freeze the rotation and re-enable the sensors
- see unfreezeRotation().
| - | RemoteException | -
|---|---|
| RemoteException - | - |
This method simply presses the power button if the screen is ON else - it does nothing if the screen is already OFF.
| - | RemoteException | -
|---|---|
| RemoteException - | - |
Performs a swipe between points in the Point array. Each step execution is throttled - to 5ms per step. So for a 100 steps, the swipe will take about 1/2 second to complete
| segments - | is Point array containing at least one Point object | -
|---|---|
| segmentSteps - | steps to inject between two Points | -
Performs a swipe from one coordinate to another using the number of steps - to determine smoothness and speed. Each step execution is throttled to 5ms - per step. So for a 100 steps, the swipe will take about 1/2 second to complete.
| steps - | is the number of move steps sent to the system | -
|---|
Take a screenshot of current window and store it as PNG - - Default scale of 1.0f (original size) and 90% quality is used - The screenshot is adjusted per screen rotation
| storePath - | where the PNG should be written to | -
|---|
Take a screenshot of current window and store it as PNG - - The screenshot is adjusted per screen rotation
| storePath - | where the PNG should be written to | -
|---|---|
| scale - | scale the screenshot down if needed; 1.0f for original size | -
| quality - | quality of the PNG compression; range: 0-100 | -
Re-enables the sensors and un-freezes the device rotation allowing its contents - to rotate with the device physical rotation. During a test execution, it is best to - keep the device frozen in a specific orientation until the test case execution has completed.
| RemoteException - | - |
|---|
Waits for the current application to idle.
| timeout - | in milliseconds | -
|---|
Waits for the current application to idle. - Default wait timeout is 10 seconds
Waits for a window content update event to occur. - - If a package name for the window is specified, but the current window - does not have the same package name, the function returns immediately.
| packageName - | the specified window package name (can be null).
- If null, a window update from any front-end window will end the wait |
-
|---|---|
| timeout - | the timeout for the wait | -
This method simulates pressing the power button if the screen is OFF else - it does nothing if the screen is already ON. - - If the screen was OFF and it just got turned ON, this method will insert a 500ms delay - to allow the device time to wake up and accept input.
| - | RemoteException | -
|---|---|
| RemoteException - | - |
A UiObject is a representation of a view. It is
-not in any way directly bound to a view as an object reference. A UiObject
-contains information to help it locate a matching view at runtime based on the
-UiSelector properties specified in
-its constructor. Once you create an instance of a UiObject, it can be reused for
-different views that match the selector criteria.
| Constants | |||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
| int | -FINGER_TOUCH_HALF_WIDTH | -- | |||||||||
| int | -SWIPE_MARGIN_LIMIT | -- | |||||||||
| long | -WAIT_FOR_EVENT_TMEOUT | -
- This constant is deprecated.
- use setScrollAcknowledgmentTimeout(long)
- |
- |||||||||
| long | -WAIT_FOR_SELECTOR_POLL | -- | |||||||||
| long | -WAIT_FOR_SELECTOR_TIMEOUT | -
- This constant is deprecated.
- use setWaitForSelectorTimeout(long)
- |
- |||||||||
| long | -WAIT_FOR_WINDOW_TMEOUT | -- | |||||||||
| Public Constructors | |||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
Constructs a UiObject to represent a view that matches the specified
- selector criteria.
-
- | |||||||||||
| Public Methods | |||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
Clears the existing text contents in an editable field.
-
- | |||||||||||
Performs a click at the center of the visible bounds of the UI element represented
- by this UiObject.
-
- | |||||||||||
Performs a click at the center of the visible bounds of the UI element represented
- by this UiObject and waits for window transitions.
-
- | |||||||||||
Waits for window transitions that would typically take longer than the
- usual default timeouts.
-
- | |||||||||||
Clicks the bottom and right corner of the UI element
-
- | |||||||||||
Clicks the top and left corner of the UI element
-
- | |||||||||||
Drags this object to a destination UiObject.
-
- | |||||||||||
Drags this object to arbitrary coordinates.
-
- | |||||||||||
Check if view exists.
-
- | |||||||||||
Returns the view's
-
- bounds property. | |||||||||||
Creates a new UiObject for a child view that is under the present UiObject.
-
- | |||||||||||
Counts the child views immediately under the present UiObject.
-
- | |||||||||||
Retrieves the
-
- className property of the UI element. | |||||||||||
Reads the
-
- content_desc property of the UI element | |||||||||||
Creates a new UiObject for a sibling view or a child of the sibling view,
- relative to the present UiObject.
-
- | |||||||||||
Reads the view's
-
- package property | |||||||||||
Debugging helper.
-
- | |||||||||||
Reads the
-
- text property of the UI element | |||||||||||
Returns the visible bounds of the view.
-
- | |||||||||||
Checks if the UI element's
-
- checkable property is currently true. | |||||||||||
Check if the UI element's
-
- checked property is currently true | |||||||||||
Checks if the UI element's
-
- clickable property is currently true. | |||||||||||
Checks if the UI element's
-
- enabled property is currently true. | |||||||||||
Check if the UI element's
-
- focusable property is currently true. | |||||||||||
Check if the UI element's
-
- focused property is currently true | |||||||||||
Check if the view's
-
- long-clickable property is currently true | |||||||||||
Check if the view's
-
- scrollable property is currently true | |||||||||||
Checks if the UI element's
-
- selected property is currently true. | |||||||||||
Long clicks the center of the visible bounds of the UI element
-
- | |||||||||||
Long clicks bottom and right corner of the UI element
-
- | |||||||||||
Long clicks on the top and left corner of the UI element
-
- | |||||||||||
Performs a multi-touch gesture.
-
- | |||||||||||
Generates a two-pointer gesture with arbitrary starting and ending points.
-
- | |||||||||||
Performs a two-pointer gesture, where each pointer moves diagonally
- toward the other, from the edges to the center of this UiObject .
-
- | |||||||||||
Performs a two-pointer gesture, where each pointer moves diagonally
- opposite across the other, from the center out towards the edges of the
- this UiObject.
-
- | |||||||||||
Sets the text in an editable field, after clearing the field's content.
-
- | |||||||||||
Performs the swipe down action on the UiObject.
-
- | |||||||||||
Performs the swipe left action on the UiObject.
-
- | |||||||||||
Performs the swipe right action on the UiObject.
-
- | |||||||||||
Performs the swipe up action on the UiObject.
-
- | |||||||||||
Waits a specified length of time for a view to become visible.
-
- | |||||||||||
Waits a specified length of time for a view to become undetectable.
-
- | |||||||||||
| Protected Methods | |||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
Finds a matching UI element in the accessibility hierarchy, by
- using the selector for this UiObject.
-
- | |||||||||||
|
- [Expand]
- Inherited Methods | |||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
|
-
-From class
-
- java.lang.Object
-
-
-
-
-
-
- | |||||||||||
-
- This constant is deprecated.
- use setScrollAcknowledgmentTimeout(long)
-
-
-
- This constant is deprecated.
- use setWaitForSelectorTimeout(long)
-
-
Constructs a UiObject to represent a view that matches the specified - selector criteria.
Clears the existing text contents in an editable field.
-
- The UiSelector of this object must reference a UI element that is editable.
-
- When you call this method, the method first sets focus at the start edge of the field.
- The method then simulates a long-press to select the existing text, and deletes the
- selected text.
-
- If a "Select-All" option is displayed, the method will automatically attempt to use it
- to ensure full text selection.
-
- Note that it is possible that not all the text in the field is selected; for example,
- if the text contains separators such as spaces, slashes, at symbol etc.
- Also, not all editable fields support the long-press functionality.
| UiObjectNotFoundException - | - |
|---|
Performs a click at the center of the visible bounds of the UI element represented - by this UiObject.
| UiObjectNotFoundException - | - |
|---|
Performs a click at the center of the visible bounds of the UI element represented
- by this UiObject and waits for window transitions.
-
- This method differ from click() only in that this method waits for a
- a new window transition as a result of the click. Some examples of a window transition:
-
| timeout - | timeout before giving up on waiting for a new window | -
|---|
| UiObjectNotFoundException - | - |
|---|
Waits for window transitions that would typically take longer than the
- usual default timeouts.
- See clickAndWaitForNewWindow(long)
| UiObjectNotFoundException - | - |
|---|
Clicks the bottom and right corner of the UI element
| UiObjectNotFoundException - | - |
|---|
Clicks the top and left corner of the UI element
| UiObjectNotFoundException - | - |
|---|
Drags this object to a destination UiObject. - The number of steps specified in your input parameter can influence the - drag speed, and varying speeds may impact the results. Consider - evaluating different speeds when using this method in your tests.
| destObj - | the destination UiObject. | -
|---|---|
| steps - | usually 40 steps. You can increase or decrease the steps to change the speed. | -
| UiObjectNotFoundException - | - |
|---|
Drags this object to arbitrary coordinates. - The number of steps specified in your input parameter can influence the - drag speed, and varying speeds may impact the results. Consider - evaluating different speeds when using this method in your tests.
| destX - | the X-axis coordinate. | -
|---|---|
| destY - | the Y-axis coordinate. | -
| steps - | usually 40 steps. You can increase or decrease the steps to change the speed. | -
| UiObjectNotFoundException - | - |
|---|
Check if view exists.
-
- This methods performs a waitForExists(long) with zero timeout. This
- basically returns immediately whether the view represented by this UiObject
- exists or not. If you need to wait longer for this view, then see
- waitForExists(long).
Returns the view's bounds property. See getVisibleBounds()
| UiObjectNotFoundException - | - |
|---|
Creates a new UiObject for a child view that is under the present UiObject.
| selector - | for child view to match | -
|---|
| UiObjectNotFoundException - | - |
|---|
Counts the child views immediately under the present UiObject.
| UiObjectNotFoundException - | - |
|---|
Retrieves the className property of the UI element.
| UiObjectNotFoundException - | if no match was found | -
|---|
Reads the content_desc property of the UI element
| UiObjectNotFoundException - | - |
|---|
Creates a new UiObject for a sibling view or a child of the sibling view, - relative to the present UiObject.
| selector - | for a sibling view or children of the sibling view | -
|---|
| UiObjectNotFoundException - | - |
|---|
Reads the view's package property
| UiObjectNotFoundException - | - |
|---|
Debugging helper. A test can dump the properties of a selector as a string
- to its logs if needed. getSelector().toString();
Reads the text property of the UI element
| UiObjectNotFoundException - | if no match could be found | -
|---|
Returns the visible bounds of the view. - - If a portion of the view is visible, only the bounds of the visible portion are - reported.
| UiObjectNotFoundException - | - |
|---|
Checks if the UI element's checkable property is currently true.
| UiObjectNotFoundException - | - |
|---|
Check if the UI element's checked property is currently true
| UiObjectNotFoundException - | - |
|---|
Checks if the UI element's clickable property is currently true.
| UiObjectNotFoundException - | - |
|---|
Checks if the UI element's enabled property is currently true.
| UiObjectNotFoundException - | - |
|---|
Check if the UI element's focusable property is currently true.
| UiObjectNotFoundException - | - |
|---|
Check if the UI element's focused property is currently true
| UiObjectNotFoundException - | - |
|---|
Check if the view's long-clickable property is currently true
| UiObjectNotFoundException - | - |
|---|
Check if the view's scrollable property is currently true
| UiObjectNotFoundException - | - |
|---|
Checks if the UI element's selected property is currently true.
| UiObjectNotFoundException - | - |
|---|
Long clicks the center of the visible bounds of the UI element
| UiObjectNotFoundException - | - |
|---|
Long clicks bottom and right corner of the UI element
| UiObjectNotFoundException - | - |
|---|
Long clicks on the top and left corner of the UI element
| UiObjectNotFoundException - | - |
|---|
Performs a multi-touch gesture. You must specify touch coordinates for
- at least 2 pointers. Each pointer must have all of its touch steps
- defined in an array of MotionEvent.PointerCoords. You can use this method to
- specify complex gestures, like circles and irregular shapes, where each
- pointer may take a different path.
-
- To create a single point on a pointer's touch path:
-
- PointerCoords p = new PointerCoords();
- p.x = stepX;
- p.y = stepY;
- p.pressure = 1;
- p.size = 1;
-
| touches - | represents the pointers' paths. Each MotionEvent.PointerCoords
- array represents a different pointer. Each MotionEvent.PointerCoords in an
- array element represents a touch point on a pointer's path. |
-
|---|
true if all touch events for this gesture are injected successfully,
- false otherwiseGenerates a two-pointer gesture with arbitrary starting and ending points.
| startPoint1 - | start point of pointer 1 | -
|---|---|
| startPoint2 - | start point of pointer 2 | -
| endPoint1 - | end point of pointer 1 | -
| endPoint2 - | end point of pointer 2 | -
| steps - | the number of steps for the gesture. Steps are injected - about 5 milliseconds apart, so 100 steps may take around 0.5 seconds to complete. | -
true if all touch events for this gesture are injected successfully,
- false otherwisePerforms a two-pointer gesture, where each pointer moves diagonally - toward the other, from the edges to the center of this UiObject .
| percent - | percentage of the object's diagonal length for the pinch gesture | -
|---|---|
| steps - | the number of steps for the gesture. Steps are injected - about 5 milliseconds apart, so 100 steps may take around 0.5 seconds to complete. | -
true if all touch events for this gesture are injected successfully,
- false otherwise| UiObjectNotFoundException - | - |
|---|
Performs a two-pointer gesture, where each pointer moves diagonally - opposite across the other, from the center out towards the edges of the - this UiObject.
| percent - | percentage of the object's diagonal length for the pinch gesture | -
|---|---|
| steps - | the number of steps for the gesture. Steps are injected - about 5 milliseconds apart, so 100 steps may take around 0.5 seconds to complete. | -
true if all touch events for this gesture are injected successfully,
- false otherwise| UiObjectNotFoundException - | - |
|---|
Sets the text in an editable field, after clearing the field's content.
-
- The UiSelector selector of this object must reference a UI element that is editable.
-
- When you call this method, the method first simulates a click() on
- editable field to set focus. The method then clears the field's contents
- and injects your specified text into the field.
-
- If you want to capture the original contents of the field, call getText() first.
- You can then modify the text and use this method to update the field.
| text - | string to set | -
|---|
| UiObjectNotFoundException - | - |
|---|
Performs the swipe down action on the UiObject. - The swipe gesture can be performed over any surface. The targeted - UI element does not need to be scrollable. - See also: -
| steps - | indicates the number of injected move steps into the system. Steps are - injected about 5ms apart. So a 100 steps may take about 1/2 second to complete. | -
|---|
| UiObjectNotFoundException - | - |
|---|
Performs the swipe left action on the UiObject. - The swipe gesture can be performed over any surface. The targeted - UI element does not need to be scrollable. - See also: -
| steps - | indicates the number of injected move steps into the system. Steps are - injected about 5ms apart. So a 100 steps may take about 1/2 second to complete. | -
|---|
| UiObjectNotFoundException - | - |
|---|
Performs the swipe right action on the UiObject. - The swipe gesture can be performed over any surface. The targeted - UI element does not need to be scrollable. - See also: -
| steps - | indicates the number of injected move steps into the system. Steps are - injected about 5ms apart. So a 100 steps may take about 1/2 second to complete. | -
|---|
| UiObjectNotFoundException - | - |
|---|
Performs the swipe up action on the UiObject. - See also: -
| steps - | indicates the number of injected move steps into the system. Steps are - injected about 5ms apart. So a 100 steps may take about 1/2 second to complete. | -
|---|
| UiObjectNotFoundException - | - |
|---|
Waits a specified length of time for a view to become visible. - - This method waits until the view becomes visible on the display, or - until the timeout has elapsed. You can use this method in situations where - the content that you want to select is not immediately displayed.
| timeout - | the amount of time to wait (in milliseconds) | -
|---|
Waits a specified length of time for a view to become undetectable.
-
- This method waits until a view is no longer matchable, or until the
- timeout has elapsed.
-
- A view becomes undetectable when the UiSelector of the object is
- unable to find a match because the element has either changed its state or is no
- longer displayed.
-
- You can use this method when attempting to wait for some long operation
- to compete, such as downloading a large file or connecting to a remote server.
| timeout - | time to wait (in milliseconds) | -
|---|
Finds a matching UI element in the accessibility hierarchy, by - using the selector for this UiObject.
| timeout - | in milliseconds | -
|---|
Generated in test runs when a UiSelector selector could not be matched
- to any UI element displayed.
-
| Public Constructors | |||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
| - - - - - - - | -- UiObjectNotFoundException(String msg) - - | ||||||||||
| - - - - - - - | -- UiObjectNotFoundException(String detailMessage, Throwable throwable) - - | ||||||||||
| - - - - - - - | -- UiObjectNotFoundException(Throwable throwable) - - | ||||||||||
|
- [Expand]
- Inherited Methods | |||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
|
-
-From class
-
- java.lang.Throwable
-
-
-
-
-
-
- | |||||||||||
|
-
-From class
-
- java.lang.Object
-
-
-
-
-
-
- | |||||||||||
A UiCollection
-that supports searching for items in scrollable layout elements. This class can
-be used with horizontally or vertically scrollable controls.
|
- [Expand]
- Inherited Constants | |||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
|
-
- From class
-com.android.uiautomator.core.UiObject
-
-
-
-
-
- | |||||||||||
| Public Constructors | |||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
Constructor.
-
- | |||||||||||
| Public Methods | |||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
Performs a backwards fling action with the default number of fling
- steps (5).
-
- | |||||||||||
Performs a forward fling with the default number of fling steps (5).
-
- | |||||||||||
Performs a fling gesture to reach the beginning of a scrollable layout element.
-
- | |||||||||||
Performs a fling gesture to reach the end of a scrollable layout element.
-
- | |||||||||||
Searches for a child element in the present scrollable container.
-
- | |||||||||||
Searches for a child element in the present scrollable container.
-
- | |||||||||||
Searches for a child element in the present scrollable container that
- matches the selector you provided.
-
- | |||||||||||
Searches for a child element in the present scrollable container.
-
- | |||||||||||
Searches for a child element in the present scrollable
- container.
-
- | |||||||||||
Gets the maximum number of scrolls allowed when performing a
- scroll action in search of a child element.
-
- | |||||||||||
Returns the percentage of a widget's size that's considered as a no-touch
- zone when swiping.
-
- | |||||||||||
Performs a backward scroll.
-
- | |||||||||||
Performs a backward scroll with the default number of scroll steps (55).
-
- | |||||||||||
Performs a forward scroll action on the scrollable layout element until
- the content-description is found, or until swipe attempts have been exhausted.
-
- | |||||||||||
Performs a forward scroll with the default number of scroll steps (55).
-
- | |||||||||||
Performs a forward scroll.
-
- | |||||||||||
Perform a scroll forward action to move through the scrollable layout
- element until a visible item that matches the selector is found.
-
- | |||||||||||
Perform a forward scroll action to move through the scrollable layout element until
- a visible item that matches the
-
- UiObject is found. | |||||||||||
Performs a forward scroll action on the scrollable layout element until
- the text you provided is visible, or until swipe attempts have been exhausted.
-
- | |||||||||||
Scrolls to the beginning of a scrollable layout element.
-
- | |||||||||||
Scrolls to the beginning of a scrollable layout element.
-
- | |||||||||||
Scrolls to the end of a scrollable layout element.
-
- | |||||||||||
Scrolls to the end of a scrollable layout element.
-
- | |||||||||||
Set the direction of swipes to be horizontal when performing scroll actions.
-
- | |||||||||||
Set the direction of swipes to be vertical when performing scroll actions.
-
- | |||||||||||
Sets the maximum number of scrolls allowed when performing a
- scroll action in search of a child element.
-
- | |||||||||||
Sets the percentage of a widget's size that's considered as no-touch
- zone when swiping.
-
- | |||||||||||
| Protected Methods | |||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
Used privately when performing swipe searches to decide if an element has become
- visible or not.
-
- | |||||||||||
|
- [Expand]
- Inherited Methods | |||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
|
-
-From class
-
- com.android.uiautomator.core.UiCollection
-
-
-
-
-
-
- | |||||||||||
|
-
-From class
-
- com.android.uiautomator.core.UiObject
-
-
-
-
-
-
- | |||||||||||
|
-
-From class
-
- java.lang.Object
-
-
-
-
-
-
- | |||||||||||
Constructor.
| container - | a UiSelector selector to identify the scrollable
- layout element. |
-
|---|
Performs a backwards fling action with the default number of fling - steps (5). If the swipe direction is set to vertical, - then the swipe will be performed from top to bottom. If the swipe - direction is set to horizontal, then the swipes will be performed from - left to right. Make sure to take into account devices configured with - right-to-left languages like Arabic and Hebrew.
| UiObjectNotFoundException - | - |
|---|
Performs a forward fling with the default number of fling steps (5). - If the swipe direction is set to vertical, then the swipes will be - performed from bottom to top. If the swipe - direction is set to horizontal, then the swipes will be performed from - right to left. Make sure to take into account devices configured with - right-to-left languages like Arabic and Hebrew.
| UiObjectNotFoundException - | - |
|---|
Performs a fling gesture to reach the beginning of a scrollable layout element. - The beginning can be at the top-most edge in the case of vertical controls, or - the left-most edge for horizontal controls. Make sure to take into - account devices configured with right-to-left languages like Arabic and Hebrew.
| UiObjectNotFoundException - | - |
|---|
Performs a fling gesture to reach the end of a scrollable layout element. - The end can be at the bottom-most edge in the case of vertical controls, or - the right-most edge for horizontal controls. Make sure to take into - account devices configured with right-to-left languages like Arabic and Hebrew.
| UiObjectNotFoundException - | - |
|---|
Searches for a child element in the present scrollable container. - The search first looks for a child element that matches the selector - you provided, then looks for the content-description in its children elements. - If both search conditions are fulfilled, the method returns a {@ link UiObject} - representing the element matching the selector (not the child element in its - subhierarchy containing the content-description).
| childPattern - | UiSelector for a child in a scollable layout element |
-
|---|---|
| text - | Content-description to find in the children of
- the childPattern match (may be a partial match) |
-
| allowScrollSearch - | set to true if scrolling is allowed | -
UiObject representing the child element that matches the search conditions| UiObjectNotFoundException - | - |
|---|
Searches for a child element in the present scrollable container.
- The search first looks for a child element that matches the selector
- you provided, then looks for the content-description in its children elements.
- If both search conditions are fulfilled, the method returns a {@ link UiObject}
- representing the element matching the selector (not the child element in its
- subhierarchy containing the content-description). By default, this method performs a
- scroll search.
- See getChildByDescription(UiSelector, String, boolean)
| childPattern - | UiSelector for a child in a scollable layout element |
-
|---|---|
| text - | Content-description to find in the children of
- the childPattern match |
-
UiObject representing the child element that matches the search conditions| UiObjectNotFoundException - | - |
|---|
Searches for a child element in the present scrollable container that - matches the selector you provided. The search is performed without - scrolling and only on visible elements.
| childPattern - | UiSelector for a child in a scollable layout element |
-
|---|---|
| instance - | int number representing the occurance of
- a childPattern match |
-
UiObject representing the child element that matches the search conditions| UiObjectNotFoundException - | - |
|---|
Searches for a child element in the present scrollable container. The - search first looks for a child element that matches the - selector you provided, then looks for the text in its children elements. - If both search conditions are fulfilled, the method returns a {@ link UiObject} - representing the element matching the selector (not the child element in its - subhierarchy containing the text).
| childPattern - | UiSelector selector for a child in a scrollable layout element |
-
|---|---|
| text - | String to find in the children of the childPattern match |
-
| allowScrollSearch - | set to true if scrolling is allowed | -
UiObject representing the child element that matches the search conditions| UiObjectNotFoundException - | - |
|---|
Searches for a child element in the present scrollable
- container. The search first looks for a child element that matches the
- selector you provided, then looks for the text in its children elements.
- If both search conditions are fulfilled, the method returns a {@ link UiObject}
- representing the element matching the selector (not the child element in its
- subhierarchy containing the text). By default, this method performs a
- scroll search.
- See getChildByText(UiSelector, String, boolean)
| childPattern - | UiSelector selector for a child in a scrollable layout element |
-
|---|---|
| text - | String to find in the children of the childPattern match |
-
UiObject representing the child element that matches the search conditions| UiObjectNotFoundException - | - |
|---|
Gets the maximum number of scrolls allowed when performing a
- scroll action in search of a child element.
- See getChildByDescription(UiSelector, String) and
- getChildByText(UiSelector, String).
Returns the percentage of a widget's size that's considered as a no-touch - zone when swiping. The no-touch zone is set as a percentage of a widget's total - width or height, denoting a margin around the swipable area of the widget. - Swipes must start and end inside this margin. This is important when the - widget being swiped may not respond to the swipe if started at a point - too near to the edge. The default is 10% from either edge.
Performs a backward scroll. If the swipe direction is set to vertical, - then the swipes will be performed from top to bottom. If the swipe - direction is set to horizontal, then the swipes will be performed from - left to right. Make sure to take into account devices configured with - right-to-left languages like Arabic and Hebrew.
| steps - | number of steps. Use this to control the speed of the scroll action. | -
|---|
| UiObjectNotFoundException - | - |
|---|
Performs a backward scroll with the default number of scroll steps (55). - If the swipe direction is set to vertical, - then the swipes will be performed from top to bottom. If the swipe - direction is set to horizontal, then the swipes will be performed from - left to right. Make sure to take into account devices configured with - right-to-left languages like Arabic and Hebrew.
| UiObjectNotFoundException - | - |
|---|
Performs a forward scroll action on the scrollable layout element until
- the content-description is found, or until swipe attempts have been exhausted.
- See setMaxSearchSwipes(int)
| text - | content-description to find within the contents of this scrollable layout element. | -
|---|
| UiObjectNotFoundException - | - |
|---|
Performs a forward scroll with the default number of scroll steps (55). - If the swipe direction is set to vertical, - then the swipes will be performed from bottom to top. If the swipe - direction is set to horizontal, then the swipes will be performed from - right to left. Make sure to take into account devices configured with - right-to-left languages like Arabic and Hebrew.
| UiObjectNotFoundException - | - |
|---|
Performs a forward scroll. If the swipe direction is set to vertical, - then the swipes will be performed from bottom to top. If the swipe - direction is set to horizontal, then the swipes will be performed from - right to left. Make sure to take into account devices configured with - right-to-left languages like Arabic and Hebrew.
| steps - | number of steps. Use this to control the speed of the scroll action | -
|---|
| UiObjectNotFoundException - | - |
|---|
Perform a scroll forward action to move through the scrollable layout
- element until a visible item that matches the selector is found.
-
- See scrollDescriptionIntoView(String) and scrollTextIntoView(String).
| selector - | UiSelector selector |
-
|---|
| UiObjectNotFoundException - | - |
|---|
Perform a forward scroll action to move through the scrollable layout element until
- a visible item that matches the UiObject is found.
| obj - | UiObject |
-
|---|
| UiObjectNotFoundException - | - |
|---|
Performs a forward scroll action on the scrollable layout element until
- the text you provided is visible, or until swipe attempts have been exhausted.
- See setMaxSearchSwipes(int)
| text - | test to look for | -
|---|
| UiObjectNotFoundException - | - |
|---|
Scrolls to the beginning of a scrollable layout element. The beginning - can be at the top-most edge in the case of vertical controls, or the - left-most edge for horizontal controls. Make sure to take into account - devices configured with right-to-left languages like Arabic and Hebrew.
| UiObjectNotFoundException - | - |
|---|
Scrolls to the beginning of a scrollable layout element. The beginning - can be at the top-most edge in the case of vertical controls, or the - left-most edge for horizontal controls. Make sure to take into account - devices configured with right-to-left languages like Arabic and Hebrew.
| steps - | use steps to control the speed, so that it may be a scroll, or fling | -
|---|
| UiObjectNotFoundException - | - |
|---|
Scrolls to the end of a scrollable layout element. The end can be at the - bottom-most edge in the case of vertical controls, or the right-most edge for - horizontal controls. Make sure to take into account devices configured with - right-to-left languages like Arabic and Hebrew.
| steps - | use steps to control the speed, so that it may be a scroll, or fling | -
|---|
| UiObjectNotFoundException - | - |
|---|
Scrolls to the end of a scrollable layout element. The end can be at the - bottom-most edge in the case of vertical controls, or the right-most edge for - horizontal controls. Make sure to take into account devices configured with - right-to-left languages like Arabic and Hebrew.
| UiObjectNotFoundException - | - |
|---|
Set the direction of swipes to be horizontal when performing scroll actions.
Set the direction of swipes to be vertical when performing scroll actions.
Sets the maximum number of scrolls allowed when performing a
- scroll action in search of a child element.
- See getChildByDescription(UiSelector, String) and
- getChildByText(UiSelector, String).
| swipes - | the number of search swipes to perform until giving up | -
|---|
Sets the percentage of a widget's size that's considered as no-touch - zone when swiping. - The no-touch zone is set as percentage of a widget's total width or height, - denoting a margin around the swipable area of the widget. Swipes must - always start and end inside this margin. This is important when the - widget being swiped may not respond to the swipe if started at a point - too near to the edge. The default is 10% from either edge.
| swipeDeadZonePercentage - | is a value between 0 and 1 | -
|---|
Used privately when performing swipe searches to decide if an element has become - visible or not.
Specifies the elements in the layout hierarchy for tests to target, filtered -by properties such as text value, content-description, class name, and state -information. You can also target an element by its location in a layout -hierarchy.
-| Public Constructors | |||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
| Public Methods | |||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
Set the search criteria to match widgets that are checkable.
-
- | |||||||||||
Set the search criteria to match widgets that
- are currently checked (usually for checkboxes).
-
- | |||||||||||
Adds a child UiSelector criteria to this selector.
-
- | |||||||||||
Set the search criteria to match the class property
- for a widget (for example, "android.widget.Button").
-
- | |||||||||||
Set the search criteria to match the class property
- for a widget (for example, "android.widget.Button").
-
- | |||||||||||
Set the search criteria to match the class property
- for a widget, using a regular expression.
-
- | |||||||||||
Set the search criteria to match widgets that are clickable.
-
- | |||||||||||
Set the search criteria to match the content-description
- property for a widget.
-
- | |||||||||||
Set the search criteria to match the content-description
- property for a widget.
-
- | |||||||||||
Set the search criteria to match the content-description
- property for a widget.
-
- | |||||||||||
Set the search criteria to match the content-description
- property for a widget.
-
- | |||||||||||
Set the search criteria to match widgets that are enabled.
-
- | |||||||||||
Set the search criteria to match widgets that are focusable.
-
- | |||||||||||
Set the search criteria to match widgets that have focus.
-
- | |||||||||||
Adds a child UiSelector criteria to this selector which is used to
- start search from the parent widget.
-
- | |||||||||||
Set the search criteria to match the widget by its node
- index in the layout hierarchy.
-
- | |||||||||||
Set the search criteria to match the
- widget by its instance number.
-
- | |||||||||||
Set the search criteria to match widgets that are long-clickable.
-
- | |||||||||||
Set the search criteria to match the package name
- of the application that contains the widget.
-
- | |||||||||||
Set the search criteria to match the package name
- of the application that contains the widget.
-
- | |||||||||||
Set the search criteria to match the given resource ID.
-
- | |||||||||||
Set the search criteria to match the resource ID
- of the widget, using a regular expression.
-
- | |||||||||||
Set the search criteria to match widgets that are scrollable.
-
- | |||||||||||
Set the search criteria to match widgets that
- are currently selected.
-
- | |||||||||||
Set the search criteria to match the visible text displayed
- in a widget (for example, the text label to launch an app).
-
- | |||||||||||
Set the search criteria to match the visible text in a widget
- where the visible text must contain the string in your input argument.
-
- | |||||||||||
Set the search criteria to match the visible text displayed in a layout
- element, using a regular expression.
-
- | |||||||||||
Set the search criteria to match visible text in a widget that is
- prefixed by the text parameter.
-
- | |||||||||||
| Protected Methods | |||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
|
- [Expand]
- Inherited Methods | |||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
|
-
-From class
-
- java.lang.Object
-
-
-
-
-
-
- | |||||||||||
Set the search criteria to match widgets that are checkable. - - Typically, using this search criteria alone is not useful. - You should also include additional criteria, such as text, - content-description, or the class name for a widget. - - If no other search criteria is specified, and there is more - than one matching widget, the first widget in the tree - is selected.
| val - | Value to match | -
|---|
Set the search criteria to match widgets that - are currently checked (usually for checkboxes). - - Typically, using this search criteria alone is not useful. - You should also include additional criteria, such as text, - content-description, or the class name for a widget. - - If no other search criteria is specified, and there is more - than one matching widget, the first widget in the tree - is selected.
| val - | Value to match | -
|---|
Adds a child UiSelector criteria to this selector. - - Use this selector to narrow the search scope to - child widgets under a specific parent widget.
Set the search criteria to match the class property - for a widget (for example, "android.widget.Button").
| className - | Value to match | -
|---|
Set the search criteria to match the class property - for a widget (for example, "android.widget.Button").
| type - | type | -
|---|
Set the search criteria to match the class property - for a widget, using a regular expression.
| regex - | a regular expression | -
|---|
Set the search criteria to match widgets that are clickable. - - Typically, using this search criteria alone is not useful. - You should also include additional criteria, such as text, - content-description, or the class name for a widget. - - If no other search criteria is specified, and there is more - than one matching widget, the first widget in the tree - is selected.
| val - | Value to match | -
|---|
Set the search criteria to match the content-description - property for a widget. - - The content-description is typically used - by the Android Accessibility framework to - provide an audio prompt for the widget when - the widget is selected. The content-description - for the widget must match exactly - with the string in your input argument. - - Matching is case-sensitive.
| desc - | Value to match | -
|---|
Set the search criteria to match the content-description - property for a widget. - - The content-description is typically used - by the Android Accessibility framework to - provide an audio prompt for the widget when - the widget is selected. The content-description - for the widget must contain - the string in your input argument. - - Matching is case-insensitive.
| desc - | Value to match | -
|---|
Set the search criteria to match the content-description - property for a widget. - - The content-description is typically used - by the Android Accessibility framework to - provide an audio prompt for the widget when - the widget is selected. The content-description - for the widget must match exactly - with the string in your input argument.
| regex - | a regular expression | -
|---|
Set the search criteria to match the content-description - property for a widget. - - The content-description is typically used - by the Android Accessibility framework to - provide an audio prompt for the widget when - the widget is selected. The content-description - for the widget must start - with the string in your input argument. - - Matching is case-insensitive.
| desc - | Value to match | -
|---|
Set the search criteria to match widgets that are enabled. - - Typically, using this search criteria alone is not useful. - You should also include additional criteria, such as text, - content-description, or the class name for a widget. - - If no other search criteria is specified, and there is more - than one matching widget, the first widget in the tree - is selected.
| val - | Value to match | -
|---|
Set the search criteria to match widgets that are focusable. - - Typically, using this search criteria alone is not useful. - You should also include additional criteria, such as text, - content-description, or the class name for a widget. - - If no other search criteria is specified, and there is more - than one matching widget, the first widget in the tree - is selected.
| val - | Value to match | -
|---|
Set the search criteria to match widgets that have focus. - - Typically, using this search criteria alone is not useful. - You should also include additional criteria, such as text, - content-description, or the class name for a widget. - - If no other search criteria is specified, and there is more - than one matching widget, the first widget in the tree - is selected.
| val - | Value to match | -
|---|
Adds a child UiSelector criteria to this selector which is used to - start search from the parent widget. - - Use this selector to narrow the search scope to - sibling widgets as well all child widgets under a parent.
Set the search criteria to match the widget by its node
- index in the layout hierarchy.
-
- The index value must be 0 or greater.
-
- Using the index can be unreliable and should only
- be used as a last resort for matching. Instead,
- consider using the instance(int) method.
| index - | Value to match | -
|---|
Set the search criteria to match the
- widget by its instance number.
-
- The instance value must be 0 or greater, where
- the first instance is 0.
-
- For example, to simulate a user click on
- the third image that is enabled in a UI screen, you
- could specify a a search criteria where the instance is
- 2, the className(String) matches the image
- widget class, and enabled(boolean) is true.
- The code would look like this:
-
- new UiSelector().className("android.widget.ImageView")
- .enabled(true).instance(2);
-
| instance - | Value to match | -
|---|
Set the search criteria to match widgets that are long-clickable. - - Typically, using this search criteria alone is not useful. - You should also include additional criteria, such as text, - content-description, or the class name for a widget. - - If no other search criteria is specified, and there is more - than one matching widget, the first widget in the tree - is selected.
| val - | Value to match | -
|---|
Set the search criteria to match the package name - of the application that contains the widget.
| name - | Value to match | -
|---|
Set the search criteria to match the package name - of the application that contains the widget.
| regex - | a regular expression | -
|---|
Set the search criteria to match the given resource ID.
| id - | Value to match | -
|---|
Set the search criteria to match the resource ID - of the widget, using a regular expression.
| regex - | a regular expression | -
|---|
Set the search criteria to match widgets that are scrollable. - - Typically, using this search criteria alone is not useful. - You should also include additional criteria, such as text, - content-description, or the class name for a widget. - - If no other search criteria is specified, and there is more - than one matching widget, the first widget in the tree - is selected.
| val - | Value to match | -
|---|
Set the search criteria to match widgets that - are currently selected. - - Typically, using this search criteria alone is not useful. - You should also include additional criteria, such as text, - content-description, or the class name for a widget. - - If no other search criteria is specified, and there is more - than one matching widget, the first widget in the tree - is selected.
| val - | Value to match | -
|---|
Set the search criteria to match the visible text displayed - in a widget (for example, the text label to launch an app). - - The text for the element must match exactly with the string in your input - argument. Matching is case-sensitive.
| text - | Value to match | -
|---|
Set the search criteria to match the visible text in a widget - where the visible text must contain the string in your input argument. - - The matching is case-sensitive.
| text - | Value to match | -
|---|
Set the search criteria to match the visible text displayed in a layout - element, using a regular expression. - - The text in the widget must match exactly with the string in your - input argument.
| regex - | a regular expression | -
|---|
Set the search criteria to match visible text in a widget that is - prefixed by the text parameter. - - The matching is case-insensitive.
| text - | Value to match | -
|---|
Represents a conditional watcher on the target device. To learn how to register a conditional
- watcher, see UiDevice.registerWatcher().
-
| Public Methods | |||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
| - abstract - - - - - boolean - | -
- checkForCondition()
-
- The testing framework calls this handler method automatically when the framework
- is unable to find a match using the
-
- UiSelector. | ||||||||||
The testing framework calls this handler method automatically when the framework is unable to find a match using the UiSelector. When a match is not found after a predetermined time has elapsed, the framework calls the checkForCondition() method of all registered watchers on the device. You can use this method to handle known blocking issues that are preventing the test from proceeding. For example, you can check if a dialog appeared that is blocking the the test, then close the dialog or perform some other appropriate action to allow the test to continue.
The {@code uiautomator} testing framework lets you test your user interface (UI) efficiently by creating automated functional UI testcases that can be run against your app on one or more devices.
-For more information on testing with the {@code uiautomator} framework, see UI Testing.
- -To run your testcases on the target device, you can use the {@code adb shell} command to invoke the {@code uiautomator} tool. The syntax is: -
-adb shell uiautomator runtest <JARS> -c <CLASSES> [options] -- -
Here’s an example:
-adb shell uiautomator runtest LaunchSettings.jar -c com.uia.example.my.LaunchSettings- -
The following table describes the subcommands and options for {@code uiautomator}.
- --Table 1. Command-line options for {@code uiautomator}
-| Subcommand | -Option | -Description | -
|---|---|---|
runtest |
-Required. The {@code <JARS>} argument is the name of one or more JAR files that you deployed to the target device which contain your uiautomator testcases. You can list more than one JAR file by using a space as a separator. | -|
-c <CLASSES> |
-Required (API 17 or lower).The {@code <CLASSES>}
-argument is a list of test classes or test methods in {@code <JARS>} to run.
- Each class or method must be fully -qualified with the package name, in one of these formats: -
Note:This argument is not required for API 18 -and higher. If not specified, all test cases in {@code <JARS>} will be run. - - |
-|
--nohup |
-Runs the test to completion on the device even if its parent process is terminated (for example, if the device is disconnected). | -|
-e <NAME> <VALUE> |
-Specify other name-value pairs to be passed to test classes. May be repeated. Note: The {@code -e} options cannot be combined; you must prefix each option with a separate {@code -e} flag. |
-|
-e debug [true|false] |
-Wait for debugger to connect before starting. | -|
dump [file] |
-Generate an XML file with a dump of the current UI hierarchy. If a filepath is not specified, by default, the generated dump file is stored on the device in this location {@code /storage/sdcard0/window_dump.xml}. | -|
-e outputFormat simple | -s |
-Enables less verbose JUnit style output. | -|
events |
-- | Prints out accessibility events to the console until the connection to the device is terminated | -
The {@code uiautomator} API is bundled in the {@code uiautomator.jar} file under the {@code <android-sdk>/platforms/} directory. The API includes these key classes, interfaces, and exceptions that allow you to capture and manipulate UI components on the target app:
- -| Class | -Description | -
|---|---|
| Used to enumerate a container's user interface (UI) elements for the purpose of counting, or targeting a sub elements by a child's text or description. | -|
| Provides access to state information about the device. You can also use this class to simulate user actions on the device, such as pressing the d-pad hardware button or pressing the Home and Menu buttons. | -|
| Represents a user interface (UI) element. | -|
| Provides support for searching for items in a scrollable UI container. | -|
| Represents a query for one or more target UI elements on a device screen. | -|
| Allows you to set key parameters for running uiautomator tests. | -
| Interface | -Description | -
|---|---|
| Represents a conditional watcher on the target device. | -|
| Provides auxiliary support for running test cases. | -|
| Defines an environment for running multiple tests. All {@code uiautomator} test cases should extend this class. | -
| Exception | -Description | -
|---|---|
| Indicates when a a {@code UiSelector} could not be matched to any UI element displayed. | -
Vector Asset Studio helps you add material icons -and import Scalable Vector Graphic (SVG) files into your app project as a drawable resource. -Compared to raster images, vector drawables can reduce the size of your app and be resized without -loss of image quality. They help you to more easily support different Android devices with varying -screen sizes and resolutions because you can display one vector drawable on all of them.
- -Vector Asset Studio adds a vector graphic to the project as an XML file that describes the image. -Maintaining one XML file can be easier than updating multiple raster graphics at various -resolutions.
- -Android 4.4 (API level 20) and lower doesn't support vector drawables. If -your minimum API level is set at one of these API levels, you have two options -when using Vector Asset Studio: -generate Portable Network Graphic (PNG) files (the default) or use the Support -Library.
- -For backward-compatibility, Vector Asset Studio generates
-raster images of the vector drawable. The vector and raster drawables are
-packaged together in the APK. You can refer to vector assets as
-{@link android.graphics.drawable.Drawable} in Java code or
-@drawable in XML code; when your app runs, the corresponding vector
-or raster image displays automatically depending on the API level.
To instead use Android Support Library 23.2 or higher, you must add
-some statements to your build.gradle file. This technique uses
-vector drawables only.
The Google material design specification provides material icons -that you can use in your Android apps. Vector -Asset Studio helps you choose, import, and size material icons, as well as -define opacity and the -Right-to-Left (RTL) mirroring setting.
- -Vector Asset Studio also helps you to import your own SVG files. SVG is an XML-based open -standard of the World Wide Web Consortium (W3C). Vector Asset Studio supports the essential -standard, but not all features. When you specify an SVG file, Vector Asset Studio gives immediate -feedback about whether the graphics code is supported or not. If the SVG code is supported, it -converts the file into an XML file containing {@link -android.graphics.drawable.VectorDrawable} code.
- -For Android 5.0 (API level 21) and higher, you can use the {@link -android.graphics.drawable.AnimatedVectorDrawable} class to animate the properties of {@link -android.graphics.drawable.VectorDrawable}. For more information, see -Animating Vector Drawables.
- -A vector drawable is appropriate for simple icons. The -material icons provide good -examples of the types -of images that work well as vector drawables in an app. In contrast, many app launch icons do have -many details, so they work better as raster images.
- -The initial loading of a vector graphic can cost more CPU cycles than the corresponding raster -image. Afterward, memory use and performance are similar between the two. We recommend that you -limit a vector image to a maximum of 200 x 200 dp; otherwise, it can take too long to draw.
- -Although vector drawables do support one or more colors, in many cases it makes sense to color
-icons black (android:fillColor="#FF000000"). Using this approach, you can add a
-tint to the vector drawable
-that you placed in a layout, and the icon color changes to the tint color. If the icon color
-isn't black, the icon color might instead blend with the tint color.
The following table summarizes the two techniques you can use for -backward-compatibility with Android 4.4 (API level 20) and lower:
- - -| Technique | -Drawables in APK | -VectorDrawable XML Elements | -Android Plugin for Gradle | -Build Flags | -App Code | -
|---|---|---|---|---|---|
| PNG generation | -Vector and raster | -Subset supported | -1.5.0 or higher | -Default | -Variety of coding techniques supported | -
| Support Library 23.2 or higher | -Vector | -Full support | -2.0 or higher | -Support Library statements required | -Subset of coding techniques supported | -
Using vector graphics can produce a smaller APK, but the initial loading -of vector graphics can take longer.
- -Android 5.0 (API level 21) and higher provides vector drawable support. If your app has a
-minimum API level that is lower, Vector Asset Studio adds the vector drawable file to your
-project; also, at build time, Gradle creates PNG raster images at various
-resolutions. Gradle generates the PNG densities specified by the Domain Specific Language (DSL)
-generatedDensities property
-in a build.gradle file. To generate PNGs, the build system requires Android
-Plugin for Gradle 1.5.0 or higher.
For Android 5.0 (API level 21) and higher, Vector Asset Studio supports all of the {@link -android.graphics.drawable.VectorDrawable} elements. For backward compatibility with Android 4.4 (API -level 20) and lower, Vector Asset Studio supports the following XML elements:
- -<vector>
android:widthandroid:heightandroid:viewportWidthandroid:viewportHeightandroid:alpha<group>
android:rotationandroid:pivotXandroid:pivotYandroid:scaleXandroid:scaleYandroid:translateXandroid:translateY<path>
android:pathDataandroid:fillColorandroid:strokeColorandroid:strokeWidthandroid:strokeAlphaandroid:fillAlphaandroid:strokeLineCapandroid:strokeLineJoinandroid:strokeMiterLimitOnly Android 5.0 (API level 21) and higher supports dynamic attributes, for example, android:fillColor="?android:attr/colorControlNormal".
You can change the XML code that Vector Asset Studio generates, although it’s not a best practice. -Changing the values in the code should not cause any issues, as long as they’re valid and static. If -you want to add XML elements, you need to make sure that they’re supported based on your minimum API -level.
- -This technique requires Android Support Library 23.2 or higher and Android
-Plugin for Gradle 2.0 or higher, and uses vector drawables only. Before using
-Vector Asset Studio, you must add a statement to your
-build.gradle file:
-android {
- defaultConfig {
- vectorDrawables.useSupportLibrary = true
- }
-}
-
-dependencies {
- compile 'com.android.support:appcompat-v7:23.2.0'
-}
-
-
- You must also use coding techniques that are compatible with the Support - Library. For more information, see - Android Support Library 23.2.
- -To start Vector Asset Studio:
- -Some other project views and folders have this menu item as well.
-Vector Asset Studio appears.
-
- Gradle syncs the project.
-Vector Asset Studio appears.
-Vector Asset Studio helps you to import a vector graphics file into your app project. Follow one - of the following procedures:
- - -After you open Vector Asset Studio, you can add a material icon as -follows:
- -The icon appears in the Vector Drawable Preview.
-The default is 24 x 24 dp, which is defined in the - material design - specification. Deselect the checkbox to return to the default.
-android:supportsRtl="true" to your app manifest. Auto-mirroring is
- supported on Android 5.0 (API level 21) and higher, and the Support Library.src/main/res, src/debug/res,
- src/release/res,
- or a user-defined source set. The main source set applies to all build variants, including
- debug and release. The debug and release source sets override the main source set and apply
- to one version of a build. The debug source set is for debugging only. To define a new source
- set, select File > Project Structure > app >
- Build Types. For example, you could define a beta source set and create a
- version of an icon that includes the text "BETA” in the bottom right corner.
- For more information, see
- Working with Build Variants.The Output Directories area displays the vector image and the directory - where it will appear.
-Vector Asset Studio adds an XML file defining the vector drawable to the project in the
- app/src/main/res/drawable/ folder. From the
- Android view of the
- Project
- window, you can view the generated vector XML file in the drawable folder.
If the minimum API level is Android 4.4 (API level 20) and lower, and you
- haven't enabled the Support Library technique, Vector Asset Studio generates
- PNG files. From the
- Project view
- of the Project window, you can view the generated PNG and XML files in the
- app/build/generated/res/pngs/debug/ folder.
You should not edit these generated raster files, but instead work with the vector XML file. - The - build system regenerates the raster files automatically when needed so you don’t need to maintain - them.
-After you open Vector Asset Studio, you can import an SVG file as -follows:
- -The file must be on a local drive. If it’s located on the network, for example, you need to - download it to a local drive first.
-The image appears in the Vector Drawable Preview.
-However, if the SVG file contains unsupported features, an error appears at the bottom left of - Vector Asset Studio, as shown in the following figure.
-
- In this case, you can’t use Vector Asset Studio to add the graphics file. Click - More to view the errors. For a list of supported elements, see - Vector Drawable Support at Different API Levels.
-The default is 24 x 24 dp, which is defined in the - material design - specification. Deselect the checkbox to return to the default.
-android:supportsRtl="true" to your app manifest. Auto-mirroring is
- supported on Android 5.0 (API level 21) and higher, and the Support Library.src/main/res, src/debug/res, src/release/res,
- or a user-defined source set. The main source set applies to all build variants, including
- debug and release. The debug and release source sets override the main source set and apply
- to one version of a build. The debug source set is for debugging only. To define a new source
- set, select File > Project Structure > app >
- Build Types. For example, you could define a beta source set and create a
- version of an icon that includes the text "BETA” in the bottom right corner.
- For more information, see
- Working with Build Variants.The Output Directories area displays the vector image and the directory - where it will appear.
-Vector Asset Studio adds an XML file defining the vector drawable to the project in the
- app/src/main/res/drawable/ folder. From the
- Android view of the
- Project
- window, you can view the generated vector XML file in the drawable folder.
If the minimum API level is Android 4.4 (API level 20) and lower, and you
- haven't enabled the Support Library technique, Vector Asset Studio generates
- PNG files. From the
- Project view
- of the Project window, you can view the generated PNG and XML files in the
- app/build/generated/res/pngs/debug/ folder.
You should not edit these generated raster files, but instead work with the vector XML file. - The - build system regenerates the raster files automatically when needed so you don’t need to maintain - them.
-In a layout file, you can set any icon-related widget, such as {@link android.widget.ImageButton}, -{@link android.widget.ImageView}, and so on, to point to a vector asset. For example, the following -layout shows a vector asset displayed on a button:
- -
-
-To display a vector asset on a widget, as shown in the figure:
- -content_main.xml.ImageButton instance and click … .The vector asset appears on the ImageButton in the layout.
The color of the image changes to the accent color in the layout.
-If you're not using the Support Library technique, the
-ImageButton code should be similar to the following:
-<ImageButton - android:id="@+id/imageButton" - android:src="@drawable/ic_build_24dp" - android:tint="@color/colorAccent" - android:layout_width="wrap_content" - android:layout_height="wrap_content" - android:layout_below="@+id/textView2" - android:layout_marginTop="168dp" /> -- -
You can normally refer to a vector drawable resource in a generic way in your code, and when -your app runs, the corresponding vector or raster image displays automatically depending on the API -level:
- -@drawable in XML code or
- {@link android.graphics.drawable.Drawable} in Java code. For example, the following layout XML code applies the image to a view:
--<ImageView - android:layout_height="wrap_content" - android:layout_width="wrap_content" - android:src="@drawable/myimage" /> --
The following Java code retrieves the image as a {@link android.graphics.drawable.Drawable}:
-
-Resources res = {@link android.content.Context#getResources()};
-Drawable drawable = res.{@link android.content.res.Resources#getDrawable(int) getDrawable}(R.drawable.myimage);
-
-
-if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.LOLLIPOP) {
- VectorDrawable vectorDrawable = (VectorDrawable) drawable;
-} else {
- BitmapDrawable bitmapDrawable = (BitmapDrawable) drawable;
-}
-
-
-
-For the Support Library technique, you must use coding techniques that are -compatible with the Support Library. For more information, see - Android Support Library 23.2.
- - -You can modify the vector asset XML code, but not the PNGs and corresponding XML code generated -at build time. However, we don't recommended it.
- -When using the PNG generation technique, Vector Asset Studio makes sure that the vector -drawable and the PNGs match, and that the manifest contains the proper code. If you add code that's -not supported on Android 4.4 (API level 20) and lower, your vector and PNG -images might differ. You also need to make sure that the manifest contains the code to support your -changes.
- -To modify the vector XML file when you're not using the Support Library -technique:
- -The XML file appears in the editor and Preview windows.
- -
-
- For example, if you didn’t select the RTL option in Vector Asset Studio but realize you now
- need it, you can add the
- autoMirrored
- attribute later. To view the RTL version, select Preview Right-to-Left Layout in
- the 
- menu of the Preview window. (Select None to remove the RTL preview.)
- Note: If you’re working with an older project, you might need to
- add android:supportsRtl="true" to your app manifest. Also, because
- autoMirrored is a dynamic attribute, it's supported on Android 5.0 (API level 21) and
- higher only.
Remember that the generated PNGs could display differently in the Preview window than - in the app due to different rendering engines and any changes made to the vector drawable before a - build. If you add code to the vector XML file created by Vector Asset Studio, any features - unsupported in Android 4.4 (API level 20) and lower don't appear in the generated PNG files. As a - result, when you add code, you should always check that the generated PNGs match the vector - drawable. To do so, you could double-click the PNG in the - Project view of the - Project - window; the left margin of the code editor also displays the PNG image when your code refers to - the drawable.
-
-To remove a vector asset from a project:
- -The Safe Delete dialog appears.
-Android Studio deletes the file from the project and the drive. However, if you chose to search - for places in the project where the file is used and some usages are found, you can view them and - decide whether to delete the file.
-Any auto-generated PNG and XML files corresponding to the deleted vector - asset are removed from the project and the drive.
-If you used the Support Library technique or your minimum API level is -Android 5.0 (API level 21) or higher, your APK will contain the vector images -that you added with Vector Asset Studio. -These APKs will be smaller than if the vector images were converted to PNGs. -
- - -When your minimum API level includes Android 4.4 (API level 20) or lower, - and you have corresponding vector and raster images in your project, - you have two options for delivering your APK files:
- -zipalign is an archive alignment tool that provides important -optimization to Android application (.apk) files. -The purpose is to ensure that all uncompressed data starts -with a particular alignment relative to the start of the file. Specifically, -it causes all uncompressed data within the .apk, such as images or raw files, -to be aligned on 4-byte boundaries. This -allows all portions to be accessed directly with {@code mmap()} even if they -contain binary data with alignment restrictions. -The benefit is a reduction in the amount of RAM consumed -when running the application.
- -This tool should always be used to align your .apk file before -distributing it to end-users. The Android build tools can handle -this for you. Android Studio automatically aligns your .apk after it signs it with your -private key. -The build scripts used -when compiling your application with Gradle also align your .apk, -as long as you have provided the path to your keystore and the key alias in -your project {@code gradle.properties} file, so that the build tools -can sign the package first.
- -Caution: zipalign must only be performed -after the .apk file has been signed with your private key. -If you perform zipalign before signing, then the signing procedure will undo -the alignment. Also, do not make alterations to the aligned package. -Alterations to the archive, such as renaming or deleting entries, will -potentially disrupt the alignment of the modified entry and all later -entries. And any files added to an "aligned" archive will not be aligned.
- -The adjustment is made by altering the size of -the "extra" field in the zip Local File Header sections. Existing data -in the "extra" fields may be altered by this process.
- -For more information about how to use zipalign when building your -application, please read Signing -Your Application.
- - -To align {@code infile.apk} and save it as {@code outfile.apk}:
- -zipalign [-f] [-v] <alignment> infile.apk outfile.apk- -
To confirm the alignment of {@code existing.apk}:
- -zipalign -c -v <alignment> existing.apk- -
The {@code <alignment>} is an integer that defines the byte-alignment boundaries. -This must always be 4 (which provides 32-bit alignment) or else it effectively -does nothing.
- -Flags:
- -This walkthrough shows the basic usage and workflow for the Allocation Tracker tool in Android - Studio. Allocation Tracker records an app's memory allocations and lists all - allocated objects for the profiling cycle with their call stack, size, and allocating code.
- -What it's good for:
- -Before using Allocation Tracker, profile your code with the - Memory - Monitor Tool. If you see many garbage collection events in a short amount of time, use - Heap - Viewer to identify candidate object types, and Allocation Tracker to determine where this is - happening in your code.
- -Allocation Tracker records each memory allocation that your app performs during the profiling - cycle. You tell Allocation Tracker to start recording and it logs allocations - until you tell it to stop.
- -- The Battery Historian chart graphs power-relevant events over time.
- -Each row shows a colored bar segment when a system component is active - and thus drawing current from the battery. The chart does not show how much battery was used by the - component, only that the app was active. Charts are organized by category.
- -
- - Figure 1. Example of Battery Historian output. -
-Note: - Not every chart will show every category.
- -You can gather additional information from the batterystats.txt file
- where you saved the output from the batterystats command.
- - Figure 2.Example of filtered batterystats output. -
-Open the file in a text editor and search for:
- -
- 
- (Start Allocation Tracking tooltip) in the Android DDMS tool bar. If you are using Android
- Studio, click the
- 
- Battery History: A time series of power-relevant events, such as
- screen, Wi-Fi, and app launch. These are also visible through Battery Historian.Per-PID Stats: How long each process ran.Statistics since last charge: System-wide statistics, such as
- cell signal levels and screen brightness. Provides an overall picture of what's happening
- with the device. This information is especially useful
- to make sure no external events are affecting your experiment.Estimated power use (mAh) by UID and peripheral: This is currently an
- extremely rough estimate and should not be considered experiment data.Per-app mobile ms per packet: Radio-awake-time divided by packets sent.
- An efficient app will transfer all its traffic in batches, so the lower this number the
- better.All partial wake locks: All app-held wakelocks, by aggregate
- duration and count.This walkthrough shows the basic usage and workflow for the Batterystats tool and the Battery - Historian script.
- -Batterystats collects battery data from your device, and Battery Historian converts that data - into an HTML visualization that you can view in your Browser. Batterystats is part of the Android - framework, and Battery Historian is open-sourced and available on GitHub at https://github.com/google/battery-historian.
- -What it's good for:
- -
- https://github.com/google/battery-historian
- > adb kill-server
- > adb devices
- > adb shell dumpsys batterystats --reset
- <disconnect and play with app>...<reconnect>
- > adb devices
- >adb shell dumpsys batterystats > batterystats.txt
- > python historian.py batterystats.txt > batterystats.html
-
- historian.py file
- and move it to the Desktop or another writable directory.historian.py,
- cd ~/Desktop> adb kill-server> adb devices
- 
- > adb shell dumpsys batterystats --reset
- Resetting erases old battery collection data; otherewise, the output will be huge.
-> adb devices> adb shell dumpsys batterystats > batterystats.txt> python historian.py batterystats.txt > batterystats.htmlbatterystats.htm file in your browser.
- Figure 1. Battery Historian output.
-
- Heap Viewer, Memory Monitor, and Allocation Tracker are complementary tools that visualize the - memory your app uses.
- -
- - Figure 1. Memory Monitor. -
-
- - Figure 2. Heap Viewer. -
-
- - Figure 3. Allocation Tracker. -
-This walkthrough shows how to visualize overdraw on your mobile device by color-coding - interface elements based on how often they are drawn underneath.
- -What it's good for:
- -This walkthrough shows the basic usage and workflow for the Heap Viewer tool. Heap Viewer - reports in real-time what types of objects your application has allocated, how many, and - their sizes on the heap.
- -What it's good for:
- -This walkthrough shows the basic usage and workflow for the Hierarchy Viewer tool.
- -The Hierarchy Viewer tool visualizes your app's view hierarchy and - profiles the relative rendering speed for each view. - -
What it's good for:
- -This walkthrough shows you how to profile your app's view hiearchy with - Hierarchy Viewer, and how to interpret the results.
- -Hierarchy Viewer measures the relative performance of a - node, so there are always red nodes in a profile, and it - doesn't necessarily mean that view is too slow for the users of - your app.
- -Hierarchy Viewer software rasterizes your Activity to acquire the timing - information. Rasterization is the process of taking a high-level primitive, such as a - circle or a vector font, and turning it into pixels on the screen. Typically, - rasterization is done by the GPU on your device, but in the case of - software rasterization, rendering is done on the CPU with - ordinary software. This means that the absolute - reported timings are correct relative to each other, but are bloated and vary - depending on the overall and changing CPU workload on your device and PC. Profile - several times to get a feel for the average measurements.
- -The following are guidelines for interpreting Hierarchy Viewer profiling output.
- -A red node is a potential problem in any situation where your app has - unexpectedly slow performance. In a relative setting, there is always a - slowest node; make sure it is the node you expect. - The following examples illustrate how to interpret red dots.
- -To run Hierarchy Viewer, you must enable Developer Options on your mobile device and perform - some setup on your computer.
- -Enable Developer Options - on your mobile device.
- 
- 
- 
- 
- 
- 
- 
- 
- 
- 
- 
- 
- 
- 
- 
- 
- 
- 
- 
- 
- 
- 
- at the top of the Tree View.
-
- 
- ANDROID_HVPROTOddm~/.bash_profile#Hierarchy Viewer Variable
-
export ANDROID_HVPROTO=ddm
- source ~/.bash_profile~/.bash_profile#Hierarchy Viewer Variable
-
export ANDROID_HVPROTO=ddm
- source ~/.bash_profileImporting some pre-Android-1.0 projects into Android 1.0 or newer can trigger a series of - errors. This document shows you how to resolve them, using a version of the Sunshine app used in - the Android Fundamentals Udacity Course as an - example.
- -CAVEAT: As with all documentation of this kind, the details are likely to vary for each - application and each update of Android Studio.
- -
- 
- If you get a Gradle error:
- -
- 
- 
- 
- build.gradle file.compileSdkVersion 21targetSdkVersion 21runProguard with minifyEnabledYour file should look like this:
-
-
-
- For the following two messages (Steps 18/19), what you see might vary. You might see either - message or both messages in sequence. Click the appropriate links to continue until the Language - Level Changed dialog opens.
- -
- 
- 
- 
- Putting pixels on the screen involves four primary pieces of hardware. - To greatly simplify, the CPU computes display lists, the GPU renders images to - the display, the memory stores images and data, and the battery provides - electrical power. Each of these pieces of hardware has constraints; pushing - or exceeding those constraints causes your app to be slow, have - bad display performance, or exhaust the battery. - -
To discover what causes your specific performance problems, you need to - take a look under the hood, use tools to collect data about your app's - execution behavior, surface that data as lists and - graphics, understand and analyze what you see, and improve your code.
- -Android Studio and your device provide profiling tools to record and - visualize the rendering, compute, memory, and battery performance of your - app.
- -- Note: While profiling an app, you should disable Instant - Run. There is a small performance impact when using Instant - Run and a slightly larger impact when updating methods. This - performance impact could interfere with information provided by performance - profiling tools. Additionally, the stub methods generated while using the - feature can complicate stack traces. -
- -Visualize the rendering behavior and performance of your app.
- -Visualize the memory behavior and performance of your app.
- -Visualize the CPU behavior and performance of your app.
- -Visualize the battery behavior and performance of your app.
- -This walkthrough shows the basic usage and workflow for the Memory Monitor tool in Android - Studio. Memory Monitor reports in real-time how your app allocates memory.
- -What it's good for:
- -This walkthrough shows how to use Profile GPU Rendering on your mobile device.
- -Profile GPU Rendering gives you a quick visual representation of how much time it takes to - render the frames of a UI window relative to the 16-ms-per-frame benchmark.
- -What it's good for:
- -- Figure 3. Enlarged Annotated Profile GPU Rendering graph. -
- -In this enlarged image of the Profile GPU Rending graph you can see the colored sections - of the graph, and what phase of the rendering pipeline each color represents.
- -Note: - While this tool is named Profile GPU Rendering, all monitored processes actually - occur in the CPU. Rendering happens by submitting commands to the GPU, and the GPU renders the - screen asynchronously. In certain situations, the GPU can have too much work to do, - and your CPU will have to wait before it can submit new commands. - When this happens, you'll see spikes in the Process (orange bar) and Execute (red bar) - stages, and the command submission will block until more room is made on the - GPU command queue. -
- -This walkthrough shows the basic usage and workflow for the Systrace tool in the Android - Device Monitor.
- -Systrace collects system and application process execution data and generates detailed, - interactive reports from devices running Android 4.1 and higher.
- -What it's good for:
- -This walkthrough shows the basic usage and workflow for the Traceview tool. Traceview logs - method execution over time and shows execution data, per-thread timelines, and call stacks.
- -What it's good for:
- -An Android project contains everything that defines your Android app, from app - source code to build configurations and test code. The SDK tools require that your projects - follow a specific structure so it can compile and package your application correctly. - If you're using Android Studio, it takes care of all this for you.
- -A module is the first level of containment within a project that encapsulates - specific types of source code files and resources. There are several types of modules - with a project:
- -
- 
- 
- 
- 
- 
.
- 
- 
- 
.
- 
- 
- 
- 
- 
- button.
- 
- 
- 
- button.
- 
- 
- 
- .apk file that gets installed on a device..apk file at build time.When you use the Android development tools to create a new project and the module, the essential files - and folders will be created for you. There are only a handful of files and folders generated for you, - and some of them depend on whether you use Android Studio or the {@code android} tool to - generate your module. As your application grows in complexity, you might require new kinds of - resources, directories, and files.
- -Note: Project folders and files apply across the entire Android -project and override similar module file settings.
- - - - -Android Studio project files and settings provide project-wide settings that apply across all - modules in the project.
- -.ideaappbuildgradle.gitignorebuild.gradlegradle.propertiesgradlewgradlew.batlocal.propertieslocal.properties should not be maintained in a source revision control system. .iml settings.gradleAndroid Application Modules are the modules that eventually get built into the .apk
- files based on your build settings. They contain things such as application source code and resource
- files. Most code and resource files are generated for you by default, while others should be created if
- required. The following directories and files comprise an Android application module:
build/libs/src/src/main/java/<namespace.appname>/<ActivityName>.java. All
- other source code files (such as .java or .aidl files) go here as
- well.androidTest/main/java/com.<project>.<app>main/jni/main/gen/R.java file and
- interfaces created from AIDL files.main/assets/.apk file as-is, and the original filename is preserved. You can
- navigate this directory in the same way as a typical file system using URIs and read files as a
- stream of bytes using the {@link android.content.res.AssetManager}. For example, this is a good
- location for textures and game data.main/res/anim/color/drawable/mipmap/mipmap folders, see
- Managing Launcher Icons as mipmap Resources.
-
-
- layout/menu/raw/assets/ directory. The only difference is how you
- access them. These files
- are processed by aapt and must be referenced from the application using a resource
- identifier in the {@code R} class. For example, this is a good place for media, such as MP3
- or Ogg files.values/res/ directory, resources written to XML files in this folder are not
- referenced by the file name. Instead, the XML element type controls how the resources
- defined within the XML files are placed into the {@code R} class.xml/AndroidManifest.xml.gitignore/app.iml/build.gradleproguard-rules.proDifferent home screen launcher apps on different devices show app launcher icons at various
-resolutions. When app resource optimization techniques remove resources for unused
-screen densities, launcher icons can wind up looking fuzzy because the launcher app has to upscale
-a lower-resolution icon for display. To avoid these display issues, apps should use the
-mipmap/ resource folders for launcher icons. The Android system
-preserves these resources regardless of density stripping, and ensures that launcher apps can
-pick icons with the best resolution for display.
Make sure launcher apps show a high-resolution icon for your app by moving all densities of your
-launcher icons to density-specific res/mipmap/ folders
-(for example res/mipmap-mdpi/ and res/mipmap-xxxhdpi/). The
-mipmap/ folders replace the drawable/ folders for launcher icons. For
-xxhpdi launcher icons, be sure to add the higher resolution xxxhdpi versions of the
-icons to enhance the visual experience of the icons on higher resolution devices.
Note: Even if you build a single APK for all devices, it is still
-best practice to move your launcher icons to the mipmap/ folders.
When you move your launcher icons to the mipmap-[density] folders, change the
-launcher icon references in the AndroidManifest.xml file so your manifest references
-the mipmap/ location. This example changes the manifest file to reference the
-ic_launcher icon in the mipmap/ folder.
-... -<application android:name="ApplicationTitle" - android:label="@string/app_label" - android:icon="@mipmap/ic_launcher" > - ... -- - - - - -
The SDK includes an example application called TicTacToeMain that shows how a
- dependent application can use code and resources from an Android Library module. The TicTacToeMain
- application uses code and resources from an example library module called TicTacToeLib.
To download the sample applications and run them as modules in - your environment, use the Android SDK Manager to download the "Samples for - SDK API 8" (or later) module into your SDK.
- -For more information and to browse the code of the samples, see - the TicTacToeMain - application.
-An Android library module is a development module that holds shared Android
- source code and resources. Other Android application modules can reference the library module
- and, at build time, include its compiled sources in their .apk files. Multiple
- application modules can reference the same library module and any single application module
- can reference multiple library modules.
Note: You need SDK Tools r14 or newer to use the new library - module feature that generates each library module into its own JAR file. - You can download the tools and platforms using the - Android SDK Manager, as described in - SDK tools help.
- -If you have source code and resources that are common to multiple Android projects, you - can move them to a library module so that it is easier to maintain across applications and - versions. Here are some common scenarios in which you could make use of library modules:
- -Structurally, a library module is similar to a standard Android application module. For
- example, it includes a manifest file at the module root, as well as src/,
- res/ and similar directories. The module can contain the same types of source
- code and resources as a standard Android module, stored in the same way. For example, source
- code in the library module can access its own resources through its R class.
However, a library module differs from a standard Android application module in that you
- cannot compile it directly to its own .apk and run it on an Android device.
- Similarly, you cannot export the library module to a self-contained JAR file, as you would do
- for a true library. Instead, you must compile the library indirectly, by referencing the
- library in the dependent application and building that application.
When you build an application that depends on a library module, the SDK tools compile the
- library into a temporary JAR file and use it in the main module, then uses the
- result to generate the .apk. In cases where a resource ID is defined in both the
- application and the library, the tools ensure that the resource declared in the application gets
- priority and that the resource in the library module is not compiled into the application
- .apk. This gives your application the flexibility to either use or redefine any
- resource behaviors or values that are defined in any library.
To organize your code further, your application can add references to multiple library - modules, then specify the relative priority of the resources in each library. This lets you - build up the resources actually used in your application in a cumulative manner. When two - libraries referenced from an application define the same resource ID, the tools select the - resource from the library with higher priority and discard the other.
- -Once you have added references to library modules to your Android application module, - you can set their relative priority. At build time, the - libraries are merged with the application one at a time, starting from the lowest priority to - the highest.
- -Library modules can reference other library modules and can import an external library - (JAR) in the normal way.
- -As you develop your library modules and dependent applications, keep the points listed below - in mind:
- -Resource conflicts
-Since the tools merge the resources of a library module with those of a dependent application - module, a given resource ID might be defined in both modules. In this case, the tools select - the resource from the application, or the library with highest priority, and discard the other - resource. As you develop your applications, be aware that common resource IDs are likely to be - defined in more than one project and will be merged, with the resource from the application or - highest-priority library taking precedence.
-Use prefixes to avoid resource conflicts
- -To avoid resource conflicts for common resource IDs, consider using a prefix or other - consistent naming scheme that is unique to the module (or is unique across all project modules).
You cannot export a library module to a JAR file
- -A library cannot be distributed as a binary file (such as a JAR file). This will be added in a - future version of the SDK Tools.
A library module can include a JAR library
- -You can develop a library module that itself includes a JAR library; however you need to - manually edit the dependent application modules's build path and add a path to the JAR file.
A library module can depend on an external JAR library
- -You can develop a library module that depends on an external library (for example, the Maps
- external library). In this case, the dependent application must build against a target that
- includes the external library (for example, the Google APIs Add-On). Note also that both the
- library module and the dependent application must declare the external library in their manifest
- files, in a <uses-library>
- element.
Library modules cannot include raw assets
- -The tools do not support the use of raw asset files (saved in the assets/ directory)
- in a library module. Any asset resources
- used by an application must be stored in the assets/ directory of the application
- module itself. However, resource files saved in the res/ directory are supported.
Platform version must be lower than or equal to the Android module
- -A library is compiled as part of the dependent application module, so the API used in the - library module must be compatible with the version of the Android library used to compile the - application module. In general, the library module should use an API level that is the same as — or lower - than — that used by the application. If the library module uses an API level that is - higher than that of the application, the application module will not compile. It is - perfectly acceptable to have a library that uses the Android 1.5 API (API level 3) and that is - used in an Android 1.6 (API level 4) or Android 2.1 (API level 7) module, for instance.
No restriction on library module names
- -There is no requirement for the package name of a library to be the same as that of - applications that use it.
Each library module creates its own R class
- -When you build the dependent application modules, library modules are compiled and
- merged with the application module. Each library has its own R class, named according
- to the library's package name. The R class generated from main
- module and the library module is created in all the packages that are needed including the main
- module's package and the libraries' packages.
Library module storage location
- -There are no specific requirements on where you should store a library module, relative to a - dependent application module, as long as the application module can reference the library - module by a relative link. What is important is that the main - module can reference the library module through a relative link.
Test projects contain Android applications that you write using the - Testing and - Instrumentation framework. The framework is an extension of the JUnit test framework and adds - access to Android system objects.
- -The test projects are now automatically part of the app source folder. When a new application
- module is created, Android Studio creates the src/androidTest source set. This
- source set contains tests for the default configuration and is combined with the debug
- build type to generate a test application.
- Figure 1. androidTest Folder.
- -Note: The src/androidTest source set may not be
- created for every type of available module template. If this source set is not created, you
- can just create it for that module.
For each product flavor, create a test folder specific to that product flavor.
- -src/main/src/androidTest/
-
- src/productFlavor1/src/testproductFlavor1/src/productFlavor2/src/testproductFlavor2/The test manifests are always generated so a manifest in a test source set is optional.
- -The test applications run against the debug build type. This can be configured
- using the testBuildType property in the build file.
For more information, see the - Testing section.
- - -There are two recommended ways of setting up testing on code and resources in a library - module:
- -The android tool provides you with commands to create all three types of
- projects. An Android project contains all of the files and resources that are needed to build a
- project into an .apk file for installation.
-
-
To create an Android project, you must use the android tool. When you create a
- new project with android, it will generate a project directory with some default
- application files, stub files, configuration files and a build file.
To create a new Android project, open a command-line, navigate to the tools/
- directory of your SDK and run:
-android create project \ ---target <target_ID> \ ---name <your_project_name> \ ---path path/to/your/project \ ---activity <your_activity_name> \ ---package <your_package_namespace> -- -
target is the "build target" for your application. It corresponds to an
- Android platform library (including any add-ons, such as Google APIs) that you would like to
- build your project against. To see a list of available targets and their corresponding IDs,
- execute: android list targets.name is the name for your project. This is optional. If provided, this name
- will be used for your .apk filename when you build your application.path is the location of your project directory. If the directory does not
- exist, it will be created for you.activity is the name for your default {@link android.app.Activity} class. This
- class file will be created for you inside
- <path_to_your_project>/src/<your_package_namespace_path>/
- . This will also be used for your .apk filename unless you provide a name.package is the package namespace for your project, following the same rules as
- for packages in the Java programming language.Here's an example:
--android create project \ ---target 1 \ ---name MyAndroidApp \ ---path ./MyAndroidAppProject \ ---activity MyAndroidAppActivity \ ---package com.example.myandroid -- -
Once you've created your project, you're ready to begin development. You can move your project
- folder wherever you want for development, but keep in mind that you must use the Android Debug Bridge (adb) — located in the
- SDK platform-tools/ directory — to send your application to the emulator (discussed
- later). So you need access between your project solution and the platform-tools/ folder.
Tip: Add the platform-tools/ as well as the tools/ directory
- to your PATH environment variable.
Caution: You should refrain from moving the location of the
- SDK directory, because this will break the SDK location property located in local.properties.
- If you need to update the SDK location, use the android update project command.
- See Updating a Project for more information.
If you're up grading a project from an older version of the Android SDK or want to create a new
- project from existing code, use the android update project command to update the
- project to the new development environment. You can also use this command to revise the build
- target of an existing project (with the --target option) and the project name (with
- the --name option). The android tool will generate any files and
- folders (listed in the previous section) that are either missing or need to be updated, as needed
- for the Android project.
To update an existing Android project, open a command-line and navigate to the
- tools/ directory of your SDK. Now run:
-android update project --name <project_name> --target <target_ID> ---path <path_to_your_project> -- -
target is the "build target" for your application. It corresponds to an
- Android platform library (including any add-ons, such as Google APIs) that you would like to
- build your project against. To see a list of available targets and their corresponding IDs,
- execute: android list targets.path is the location of your project directory.name is the name for the project. This is optional—if you're not
- changing the project name, you don't need this.Here's an example:
--android update project --name MyApp --target 2 --path ./MyAppProject -- -
A library project is a standard Android project, so you can create a new one in the same way
- as you would a new application project. Specifically, you can use the android tool
- to generate a new library project with all of the necessary files and folders.
To create a new library project, navigate to the <sdk>/tools/ directory and
- use this command:
-android create lib-project --name <your_project_name> \ ---target <target_ID> \ ---path path/to/your/project \ ---package <your_library_package_namespace> -- -
The create lib-project command creates a standard project structure that includes
- preset property that indicates to the build system that the project is a library. It does this by
- adding this line to the project's project.properties file:
-android.library=true -- -
Once the command completes, the library project is created and you can begin moving source - code and resources into it, as described in the sections below.
- -If you want to convert an existing application project to a library project, so that other
- applications can use it, you can do so by adding a the android.library=true property
- to the application's project.properties file.
A library project's manifest file must declare all of the shared components that it includes, - just as would a standard Android application. For more information, see the documentation for - AndroidManifest.xml.
- -For example, the TicTacToeLib example library
- project declares the Activity GameActivity:
-<manifest> - ... - <application> - ... - <activity android:name="GameActivity" /> - ... - </application> -</manifest> -- -
If you want to update the build properties (build target, location) of the library project, - use this command:
--android update lib-project \ ---target <target_ID> \ ---path path/to/your/project -- -
If you are developing an application and want to include the shared code or resources from a - library project, you can do so easily by adding a reference to the library project in the - application project's build properties.
- -To add a reference to a library project, navigate to the <sdk>/tools/
- directory and use this command:
-android update project \ ---target <target_ID> \ ---path path/to/your/project ---library path/to/library_projectA -- -
This command updates the application project's build properties to include a reference to the
- library project. Specifically, it adds an android.library.reference.n
- property to the project's project.properties file. For example:
-android.library.reference.1=path/to/library_projectA -- -
If you are adding references to multiple libraries, note that you can set their relative
- priority (and merge order) by manually editing the project.properties file and
- adjusting the each reference's .n index as appropriate. For example, assume
- these references:
-android.library.reference.1=path/to/library_projectA -android.library.reference.2=path/to/library_projectB -android.library.reference.3=path/to/library_projectC -- -
You can reorder the references to give highest priority to library_projectC in
- this way:
-android.library.reference.2=path/to/library_projectA -android.library.reference.3=path/to/library_projectB -android.library.reference.1=path/to/library_projectC -- -
Note that the .n index in the references must begin at "1" and increase
- uniformly without "holes". References appearing in the index after a hole are ignored.
At build time, the libraries are merged with the application one at a time, starting from the - lowest priority to the highest. Note that a library cannot itself reference another library and - that, at build time, libraries are not merged with each other before being merged with the - application.
- -In the manifest file of the application project, you must add declarations of all components
- that the application will use that are imported from a library project. For example, you must
- declare any <activity>, <service>,
- <receiver>, <provider>, and so on, as well as
- <permission>, <uses-library>, and similar elements.
Declarations should reference the library components by their fully-qualified package names, - where appropriate.
- -For example, the TicTacToeMain example
- application declares the library Activity GameActivity like this:
-<manifest> - ... - <application> - ... - <activity android:name="com.example.android.tictactoe.library.GameActivity" /> - ... - </application> -</manifest> -- -
For more information about the manifest file, see the documentation for - AndroidManifest.xml.
- -To build an application project that depends on one or more library projects, you can use the - standard Gradle build commands and compile modes, as described in Building and Running. The tools -compile and merge all libraries referenced by the application as part of - compiling the dependent application project. No additional commands or steps are necessary.
- diff --git a/docs/html/tools/projects/templates.jd b/docs/html/tools/projects/templates.jd deleted file mode 100644 index 74260104a2555e37c9e9941a264ccef45abec05d..0000000000000000000000000000000000000000 --- a/docs/html/tools/projects/templates.jd +++ /dev/null @@ -1,366 +0,0 @@ -page.title=Using Code Templates -page.image=images/cards/card-using-code-templates_16x9_2x.png -page.metaDescription=Quickly create Android app projects with various UI or functional components. -page.tags=studio,templates,firstapp -@jd:body - -The SDK tools provide templates for quickly creating Android application projects with the basic - structure or for adding components to your existing application modules. The code templates - provided by the Android SDK follow the Android design and development guidelines to get you on the - right track to creating a beautiful, functional application.
- -There are several types of Android code templates, which can create anything from an entire - application down to specific application components. The main categories of code templates are as - follows:
- - - -- The templates use support library objects - if such objects are available. The support library objects make new features - available on the widest range of platforms. For example, since the templates - use the appcompat - library, apps based on the templates use material design user interface - principles even if they are running on older Android devices that do not - directly support material design. -
- -Application templates create basic Android application modules that you can immediately run and test - on your Android device. These templates are available when you create a new Android module, - though you can also use these templates to add new activities - to an existing module.
- -To use Android application templates:
- -- Note: The other activity template options also create applications, however these - applications require further modification before they can be launched on an Android device. -
- - -| Example | - -Description | -
|---|---|
- |
-
- The BlankActivity template with the Navigation Type: - None option creates a simple application that follows the - Android Design guidelines. Use this template to - create a basic, minimal app as a starting point for your project. - -This template includes: - -
|
-
- |
-
- The BlankActivity template with the Navigation Type: - Tabs or Tabs + Swipe option creates an application with - three sections based on the {@link android.app.Fragment} class and a tabbed user - interface. - -This template includes: - -
|
-
- |
-
- The BlankActivity template with the Navigation Type: - Swipe Views + Title Strip option creates an application with three - {@link android.app.Fragment} sections, a compact title strip header (known as - Scrollable Tabs in the - Android Design guide) and swipe navigation between - the sections, based on the swipe - view design pattern. - -This template includes: - -
|
-
- |
-
- The BlankActivity template with the Navigation Type: - Dropdown option creates an application that extends - {@link android.support.v4.app.FragmentActivity}, containing three - {@link android.app.Fragment} sections, with an {@link android.app.ActionBar} using list mode - navigation. - -This template includes: - -
|
-
| Example | - -Description | -
|---|---|
- |
-
- This template provides an implementation of an activity which alternates between a - primary, full screen view and a view with standard user interface controls, including the - notification bar and application title bar. The full screen view is the default and a user - can activate the standard view by touching the device screen. - -This template includes: - -
|
-
| Example | - -Description | -
|---|---|
- |
-
- This template creates an adaptive layout for a set of items and associated details. On a - tablet device, the item list and item details are displayed on the same screen. On a smaller - device, the list and details are displayed on separate screens. - -- Note: This template follows the recommendations of the - Designing for Multiple Screens - Android training. - - -This template includes: - -
|
-
Android activity templates provide options to add new activities to your existing - application.
- -To use Android activity templates:
- -These templates create the same type of activity as they do when used as an application template, -however the following templates create activities which are specifically intended to be used as part -of an existing application.
- - -| Example | - -Description | -
|---|---|
- |
-
- This activity template provides input fields and a sample implementation of - an {@link android.os.AsyncTask} that asks users to login or register with their credentials. - -This template includes: - -
|
-
| Example | - -Description | -
|---|---|
- |
-
- This template extends the {@link android.preference.PreferenceActivity} class and uses an - XML file to create preference settings. This template also demonstrates how to implement - several data types for settings. - -This template includes: - -
|
-
Android object templates provide options to add new components to your existing application, -including the previously mentioned activities as well as the following additional items:
- -To use Android object templates:
- -Android requires that all apps be digitally signed with a certificate before they can be -installed. Android uses this certificate to identify the author of an app, and the certificate -does not need to be signed by a certificate authority. Android apps often use self-signed -certificates. The app developer holds the certificate's private key.
- - -You can sign an app in debug or release mode. You sign your app in debug mode during development -and in release mode when you are ready to distribute your app. The Android SDK generates a -certificate to sign apps in debug mode. To sign apps in release mode, you need to generate -your own certificate.
- -In debug mode, you sign your app with a debug certificate generated by the Android SDK tools. -This certificate has a private key with a known password, so you can run and debug your app -without typing the password every time you make a change to your project.
- -Android Studio signs your app in debug mode automatically when -you run or debug your project from the IDE.
- -You can run and debug an app signed in debug mode on the emulator and on devices connected -to your development machine through USB, but you cannot distribute an app signed in debug -mode.
- -By default, the debug configuration uses a debug keystore, with a known
-password and a default key with a known password.
-The debug keystore is located in $HOME/.android/debug.keystore, and
-is created if not present.
-The debug build type is set to use this debug SigningConfig automatically.
For more information about how to build and run apps in debug mode, see -Building and Running.
- -In release mode, you sign your app with your own certificate:
- -Add the signing configuration to the build file for the app module:
-...
-android {
- ...
- defaultConfig { ... }
- signingConfigs {
- release {
- storeFile file("myreleasekey.keystore")
- storePassword "password"
- keyAlias "MyReleaseKey"
- keyPassword "password"
- }
- }
- buildTypes {
- release {
- ...
- signingConfig signingConfigs.release
- }
- }
-}
-...
-
- assembleRelease build task from Android Studio.The package in app/build/apk/app-release.apk is now signed with your release
-key.
Note: Including the passwords for your release key and keystore -inside the build file is not a good security practice. Alternatively, you can configure the build -file to obtain these passwords from environment variables or have the build process prompt you -for these passwords.
- -To obtain these passwords from environment variables:
- -
-storePassword System.getenv("KSTOREPWD")
-keyPassword System.getenv("KEYPWD")
-
-
-To have the build process prompt you for these passwords if you are invoking the build from -the command line:
- -
-storePassword System.console().readLine("\nKeystore password: ")
-keyPassword System.console().readLine("\nKey password: ")
-
-
-
-After you complete this process, you can distribute your app and publish it on Google Play.
- -Warning: Keep your keystore and private key in a safe and -secure place, and ensure that you have secure backups of them. If you publish an app to Google -Play and then lose the key with which you signed your app, you will not be able to publish -any updates to your app, since you must always sign all versions of your app with the same -key.
- -The rest of this document provides detailed instructions about how to generate a private -key and sign your apps in release mode with Android Studio.
- -When publishing Android Wear apps, you package the wearable app inside of a handheld app, -because users cannot browse and install apps directly on the wearable. Both apps must be signed. -For more information on packaging and signing Android Wear apps, see -Packaging Wearable Apps.
- - -To sign your app in release mode in Android Studio, follow these steps:
- -On the Generate Signed APK Wizard window, click Create new to -create a new keystore.
-If you already have a keystore, go to step 4.
On the New Key Store window, provide the required information as shown -in figure 1.
-Your key should be valid for at least 25 years, so you can sign app updates -with the same key through the lifespan of your app.
-
-Figure 1. Create a new keystore in Android Studio.
-On the Generate Signed APK Wizard window, select a keystore, a private key, and -enter the passwords for both. Then click Next.
-
-Figure 2. Select a private key in Android Studio.
-- On the next window, select a destination for the signed APK(s), select the - build type, (if applicable) choose the product flavor(s), and click - Finish.
-
-- Figure 3. Generate signed APKs for the selected product - flavors. -
-- Note: If your project uses product flavors, you can select - multiple product flavors while holding down the Ctrl key on - Windown/Linux, or the Command key on Mac OSX. Android Studio - will generate a separate APK for each selected product flavor. -
- -In Android Studio, you can configure your project to sign your release APK automatically -during the build process:
- -Select your keystore file, enter a name for this signing configuration (as you may create -more than one), and enter the required information.
-
-Figure 4. Create a signing configuration in Android -Studio.
-Under Signing Config, select the signing configuration you just created.
-
-Figure 5. Select a signing configuration in Android -Studio.
-You can also specify your signing settings in Gradle configuration files. For more information, -see Configuring Gradle -Builds.
- - - -You should sign all of your apps with the same certificate throughout the expected lifespan -of your applications. There are several reasons why you should do so:
- -If you plan to support upgrades for an app, ensure that your key has a validity -period that exceeds the expected lifespan of that app. A validity period of 25 years or more is -recommended. When your key's validity period expires, users will no longer be able to seamlessly -upgrade to new versions of your application.
- -If you plan to publish your apps on Google Play, the key you use to sign these apps must have -a validity period ending after 22 October 2033. Google Play enforces this requirement to ensure -that users can seamlessly upgrade apps when new versions are available.
- - -Maintaining the security of your private key is of critical importance, both to you and to -the user. If you allow someone to use your key, or if you leave your keystore and passwords in -an unsecured location such that a third-party could find and use them, your authoring identity -and the trust of the user are compromised.
- -If a third party should manage to take your key without your knowledge or permission, that -person could sign and distribute apps that maliciously replace your authentic apps or corrupt -them. Such a person could also sign and distribute apps under your identity that attack -other apps or the system itself, or corrupt or steal user data.
- -Your private key is required for signing all future versions of your app. If you lose or -misplace your key, you will not be able to publish updates to your existing appn. You cannot -regenerate a previously generated key.
- -Your reputation as a developer entity depends on your securing your private key properly, at -all times, until the key is expired. Here are some tips for keeping your key secure:
- -In general, if you follow common-sense precautions when generating, using, and storing -your key, it will remain secure.
- - -The self-signed certificate used to sign your application in debug mode has an expiration date -of 365 days from its creation date. When the certificate expires, you will get a build error.
- -To fix this problem, simply delete the debug.keystore file. The default storage
-location is in ~/.android/ on OS X and Linux, in C:\Documents and
-Settings\<user>\.android\ on Windows XP, and in
-C:\Users\<user>\.android\ on Windows Vista and Windows 7.
The next time you build and run your app, the build tools will regenerate a - new keystore and debug key. Note that you must run your app, building alone - does not regenerate the keystore and debug key.
- - -You do not need Android Studio to sign your app. You can sign -your app from the command line using standard tools from the Android SDK and the JDK. To sign -an app in release mode from the command line:
- -Generate a private key using
- keytool.
- For example:
-$ keytool -genkey -v -keystore my-release-key.keystore --alias alias_name -keyalg RSA -keysize 2048 -validity 10000 --
This example prompts you for passwords for the keystore and key, and to provide the
- Distinguished Name fields for your key. It then generates the keystore as a file called
- my-release-key.keystore. The keystore contains a single key, valid for 10000 days.
- The alias is a name that you will use later when signing your app.
Compile your app in release mode to obtain an unsigned APK.
-Sign your app with your private key using
- jarsigner:
-
-$ jarsigner -verbose -sigalg SHA1withRSA -digestalg SHA1 --keystore my-release-key.keystore my_application.apk alias_name --
This example prompts you for passwords for the keystore and key. It then modifies the APK - in-place to sign it. Note that you can sign an APK multiple times with different keys.
-Verify that your APK is signed. For example:
--$ jarsigner -verify -verbose -certs my_application.apk --
Align the final APK package using
- zipalign.
-$ zipalign -v 4 your_project_name-unaligned.apk your_project_name.apk --
zipalign ensures that all uncompressed data starts with a particular byte
- alignment relative to the start of the file, which reduces the amount of RAM consumed by an
- app.
Before you distribute your Android application to users you need to prepare it for release. The -preparation process is a required development -task for all Android applications and is the first step in the publishing process (see figure -1).
- -When you prepare your application for release, you configure, build, and test a release
-version of your application. The configuration tasks are straightforward, involving basic code
-cleanup and code modification tasks that help optimize your application. The build process is
-similar to the debug build process and can be done using JDK and Android SDK tools. The testing
-tasks serve as a final check, ensuring that your application performs as expected under real-world
-conditions. When you are finished preparing your application for release you have a signed
-.apk file, which you can distribute directly to users or distribute through an
-application marketplace such as Google Play.
This document summarizes the main tasks you need to perform to prepare your application for -release. The tasks that are described in this document apply to all Android applications regardless -how they are released or distributed to users. If you are releasing your application through Google -Play, you should also read Publishing -Checklist for Google Play to be sure your release-ready application satisfies all Google Play -requirements.
- -Note: As a best practice, your application should meet all of your -release criteria for functionality, performance, and stability before you perform the tasks outlined -in this document.
- -
-- Figure 1. Preparing for release is a required development -task and is the first step in the publishing process. -
- -To release your application to users you need to create a release-ready package that users can
-install and run on their Android-powered devices. The release-ready package contains the same
-components as the debug .apk file — compiled source code, resources, manifest
-file, and so on — and it is built using the same build tools. However, unlike the debug
-.apk file, the release-ready .apk file is signed with your own certificate
-and it is optimized with the zipalign tool.
- - Figure 2. You perform five main tasks to prepare your application for - release. -
-The signing and optimization tasks are usually seamless if you are building your application with -Android Studio. For example, you can use Android Studio with the Gradle build files to compile, sign, -and optimize your application all at once. You can also configure the Gradle build files to do the -same when you build from the command line. For more details about using the Gradle build files, see -the Build System guide.
- -To prepare your application for release you typically perform five main tasks (see figure 2). -Each main task may include one or more smaller tasks depending on how you are releasing your -application. For example, if you are releasing your application through Google Play you may want -to add special filtering rules to your manifest while you are configuring your application for -release. Similarly, to meet Google Play publishing guidelines you may have to prepare screenshots -and create promotional text while you are gathering materials for release.
- -You usually perform the tasks listed in figure 2 after you have throroughly debugged and tested -your application. The Android SDK contains several tools to help you test and debug your Android -applications. For more information, see the Debugging and Testing sections in the Dev Guide.
- -To begin preparing your application for release you need to gather several supporting items. At a -minimum this includes cryptographic keys for signing your application and an application icon. You -might also want to include an end-user license agreement.
- -The Android system requires that each installed application be digitally signed with a -certificate that is owned by the application's developer (that is, a certificate for which the -developer holds the private key). The Android system uses the certificate as a means of identifying -the author of an application and establishing trust relationships between applications. The -certificate that you use for signing does not need to be signed by a certificate authority; the -Android system allows you to sign your applications with a self-signed certificate. To learn about -certificate requirements, see Signing Your -Applications.
- -Important: Your application must be signed with a cryptographic -key whose validity period ends after 22 October 2033.
- -You may also have to obtain other release keys if your application accesses a service or uses a -third-party library that requires you to use a key that is based on your private key. For example, -if your application uses the MapView -class, which is part of the Google Maps external -library, you will need to register your application with the Google Maps service and obtain -a Maps API key. For information about getting a Maps API key, see Obtaining a Maps API -key.
- -Be sure you have an application icon and that it meets the recommended icon guidelines. Your -application's icon helps users identify your application on a device's Home -screen and in the Launcher window. It also appears in Manage Applications, My Downloads, and -elsewhere. In addition, publishing services such as Google Play display your icon to users.
- -Note: If you are releasing your application on Google Play, you -need to create a high resolution - version of your icon. See Graphic -Assets for your Application for more information.
- -Consider preparing an End User License Agreement (EULA) for your application. A EULA can help -protect your person, organization, and intellectual property, and we recommend that you provide one -with your application.
- -You might also have to prepare promotional and marketing materials to publicize your application. -For example, if you are releasing your application on Google Play you will need to prepare some -promotional text and you will need to create screenshots of your application. For more -information, see - -Graphic Assets for your Application
- -After you gather all of your supporting materials you can start configuring your application -for release. This section provides a summary of the configuration changes we recommend that you make -to your source code, resource files, and application manifest prior to releasing your application. -Although most of the configuration changes listed in this section are optional, they are -considered good coding practices and we encourage you to implement them. In some cases, -you may have already made these configuration changes as part of your development process.
- -Make sure you choose a package name that is suitable over the life of your application. You -cannot change the package name after you distribute your application to users. You can set the -package name in application's manifest file. For more information, see the package attribute -documentation.
- -Make sure you deactivate logging and disable the debugging option before you build your
-application for release. You can deactivate logging by removing calls to
-{@link android.util.Log} methods in your source files. You can disable debugging by removing the
-android:debuggable attribute from the <application> tag in your
-manifest file, or by setting the android:debuggable attribute to
-false in your manifest file. Also, remove any log files or static test files that
-were created in your project.
Also, you should remove all {@link android.os.Debug} tracing calls that you -added to your code, such as {@link android.os.Debug#startMethodTracing()} and -{@link android.os.Debug#stopMethodTracing()} method calls.
- -Important: Ensure that you disable debugging for -your app if using {@link android.webkit.WebView} to display paid for content or if using JavaScript -interfaces, since debugging allows users to inject scripts and extract content using Chrome -DevTools. To disable debugging, use the -{@link android.webkit.WebView#setWebContentsDebuggingEnabled(boolean) WebView.setWebContentsDebuggingEnabled()} -method.
- -Clean up your project and make sure it conforms to the directory structure described in Android Projects. -Leaving stray or orphaned files in your project can prevent your application from compiling and -cause your application to behave unpredictably. At a minimum you should do the following cleanup -tasks:
- -jni/, lib/, and src/
- directories. The jni/ directory should contain only source files associated with the
- Android NDK, such as
- .c, .cpp, .h, and .mk files. The
- lib/ directory should contain only third-party library files or private library
- files, including prebuilt shared and static libraries (for example, .so files). The
- src/ directory should contain only the source files for your application
- (.java and .aidl files). The src/ directory should not
- contain any .jar files.res/ directory for old
- drawable files, layout files, and values files that you are no longer using and delete them.lib/ directory for test libraries and remove them if they are no
- longer being used by your application.assets/ directory and your res/raw/
- directory for raw asset files and static files that you need to update or remove prior to
- release.Verify that the following manifest and build files items are set correctly:
- -You should specify only those permissions that are relevant and required for your application.
-android:icon and android:label attributes
- You must specify values for these attributes, which are located in the - <application> - element.
-android:versionCode and android:versionName attributes.
- We recommend that you specify values for these attributes, which are located in the - <manifest> - element. For more information see - Versioning your Application.
-There are several additional manifest or build file elements that you can set if you are releasing your
-application on Google Play. For example, the android:minSdkVersion and
-android:targetSdkVersion attributes, which are located in the <uses-sdk> element. For more
-information about these and other Google Play settings, see Filters on Google Play.
Android provides several tools and techniques to make your application compatible with a wide -range of devices. To make your application available to the largest number of users, consider -doing the following:
- -Make sure you meet the - - best practices for supporting multiple screens. By supporting multiple screen configurations - you can create an application that functions properly and looks good on any of the screen sizes - supported by Android.
-If your application is designed for devices older than Android 3.0, make it compatible - with Android 3.0 devices by following the guidelines and best practices described in - Optimizing Apps for Android 3.0 - .
-If your application is designed for devices running Android 3.x, make your application - compatible with older versions of Android by adding the - Support Library to your - application project. The Support Library provides static support libraries that you can add to - your Android application, which enables you to use APIs that are either not available on - older platform versions or use utility APIs that are not part of the framework APIs.
-If your application accesses remote servers or services, make sure you are using the production -URL or path for the server or service and not a test URL or path.
- -If you are releasing a paid application through Google Play, consider adding support for -Google Play Licensing. Licensing lets you control access to your application based on whether the -current user has purchased it. Using Google Play Licensing is optional even if you are -releasing your app through Google Play.
- -For more information about Google Play Licensing Service and how to use it in your -application, see Application Licensing.
- -After you finish configuring your application you can build it into a release-ready
-.apk file that is signed and optimized. The JDK includes the tools for signing the
-.apk file (Keytool and Jarsigner); the Android SDK includes the tools for compiling and
-optimizing the .apk file. If you are using Android Studio or you are using
-the Gradle build system from the command line, you can automate the entire build process.
-For more information about configuring Gradle builds, see
-Configuring Gradle Builds.
You can use the Gradle build system, integrated with Android Studio to build a release-ready
-.apk file that is signed with your private key and optimized. To learn how to setup and
-run builds from Android Studio, see
-Building and Running from Android Studio.
The build process assumes that you have a certificate and private key -suitable for signing your application. If you do not have a suitable certificate and private key, -Android Studio can help you generate one. For more information about the signing process, see -Signing Your Applications.
- - -If your application relies on a remote server, make sure the server is secure and that it is -configured for production use. This is particularly important if you are implementing in-app billing in your application and you are -performing the signature verification step on a remote server.
- -Also, if your application fetches content from a remote server or a real-time service (such as a -content feed), be sure the content you are providing is up to date and production-ready.
- -Testing the release version of your application helps ensure that your application runs properly -under realistic device and network conditions. Ideally, you should test your application on at least -one handset-sized device and one tablet-sized device to verify that your user interface elements are -sized correctly and that your application's performance and battery efficiency are acceptable.
- -As a starting point for testing, see -What to Test. This article provides -a summary of common Android situations that you should consider when you are testing. When you are -done testing and you are satisfied that the release version of your application -behaves correctly, you can release your application to users. For more information, see -Releasing Your -Application to Users. If you are publishing your application on Google Play, see -Launch Checklist -for Google Play.
- - diff --git a/docs/html/tools/publishing/publishing_overview.jd b/docs/html/tools/publishing/publishing_overview.jd deleted file mode 100644 index 167758a279bd850233224bcb33cc3f6d883d7e01..0000000000000000000000000000000000000000 --- a/docs/html/tools/publishing/publishing_overview.jd +++ /dev/null @@ -1,242 +0,0 @@ -page.title=Publishing Overview -page.metaDescription=Start here for an overview of publishing options for Android apps. -@jd:body - -Publishing is the general process that makes your Android applications available to users. When you -publish an Android application you perform two main tasks:
- -During the preparation step you build a release version of your application, which users can - download and install on their Android-powered devices.
-During the release step you publicize, sell, and distribute the release version of your - application to users.
-Usually, you release your application through an application marketplace, such as Google Play. -However, you can also release applications by sending them directly to users or by letting users -download them from your own website.
- -Figure 1 shows how the publishing process fits into the overall Android application development process. -The publishing process is typically performed after you finish testing your application in a debug -environment. Also, as a best practice, your application should meet all of your release criteria for -functionality, performance, and stability before you begin the publishing process.
- -
-- Figure 1. Publishing is the last phase of the Android application development process. -
- -Preparing your application for release is a multi-step process that involves the following -tasks:
- -At a minimum you need to remove {@link android.util.Log} calls and remove the
- android:debuggable
- attribute from your manifest file. You should also provide values for the
- android:versionCode and android:versionName attributes, which are
- located in the
- <manifest>
- element. You may also have to configure several other settings to meet Google Play
- requirements or accomodate whatever method you're using to release your application.
If you are using Gradle build files, you can use the release build type to set - your build settings for the published version of your app.
-You can use the Gradle build files with the release build type to build and sign a - release version of your application. See - Building and Running from Android - Studio.
-Before you distribute your application, you should thoroughly test the release version on at - least one target handset device and one target tablet device.
-You need to be sure that all application resources such as multimedia files and graphics - are updated and included with your application or staged on the proper production servers.
-If your application depends on external servers or services, you need to be sure they - are secure and production ready.
-You may have to perform several other tasks as part of the preparation process. For example, you -will need to get a private key for signing your application, and you may need to get a Maps API -release key if you are using the Google Maps external -library. You will also need to create an icon for your application, and you may want to prepare -an End User License Agreement (EULA) to protect your person, organization, and intellectual -property.
- -When you are finished preparing your application for release you will have a signed
-.apk file that you can distribute to users.
To learn how to prepare your application for release, see Preparing for Release in the Dev Guide. This -topic provides step-by-step instructions for configuring and building a release version of your -application.
- -You can release your Android applications several ways. Usually, you release applications -through an application marketplace such as Google Play, but you can also release applications -on your own website or by sending an application directly to a user. - -
If you want to distribute your apps to the broadest possible audience, releasing through -an app marketplace such as Google Play is ideal.
- -Google Play is the premier marketplace for Android apps and is particularly -useful if you want to distribute your applications to a large global audience. -However, you can distribute your apps through any app marketplace you want or -you can use multiple marketplaces.
- - -Google Play is a robust publishing platform that helps you publicize, sell, and distribute -your Android applications to users around the world. When you release your applications through -Google Play you have access to a suite of developer tools that let you analyze your sales, -identify market trends, and control who your applications are being distributed to. You also have -access to several revenue-enhancing features such as in-app billing and application licensing. The rich array of tools -and features, coupled with numerous end-user community features, makes Google Play the premier -marketplace for selling and buying Android applications.
- -Releasing your application on Google Play is a simple process that involves three basic - steps:
- -To fully leverage the marketing and publicity capabilities of Google Play, you need to - create promotional materials for your application, such as screenshots, videos, graphics, and - promotional text.
-Google Play lets you target your application to a worldwide pool of users and devices. - By configuring various Google Play settings, you can choose the countries you want to - reach, the listing languages you want to use, and the price you want to charge in each - country. You can also configure listing details such as the application type, category, and - content rating. When you are done configuring options you can upload your promotional materials - and your application as a draft (unpublished) application.
-If you are satisfied that your publishing settings are correctly configured and your - uploaded application is ready to be released to the public, you can simply click - Publish in the developer console and within minutes your application will be - live and available for download around the world.
-For information complete information, see Google Play.
- - -
- - Figure 1. Users can simply click Install when you send them - an application via email. -
-The easiest and quickest way to release your application is to send it to a user through -email. To do this, you prepare your application for release and then attach it to an email -and send it to a user. When the user opens your email message on their Android-powered device -the Android system will recognize the APK and display an Install Now -button in the email message (see figure 1). Users can install your application by touching the -button.
- -Note: The Install Now button -shown in Figure 1 appears only if a user has configured their device to allow -installation from unknown sources and has opened your -email with the native Gmail application.
- -Distributing applications through email is convenient if you are sending your application to -only a few trusted users, but it provides few protections from piracy and unauthorized -distribution; that is, anyone you send your application to can simply forward it to someone else.
- -If you do not want to release your app on a marketplace like Google Play, you -can make the app available for download on your own website or server, including -on a private or enterprise server. To do this, you must first prepare your -application for release in the normal way. Then all you need to do is host the -release-ready APK file on your website and provide a download link to users. -
- -When users browse to the download link from their Android-powered devices, -the file is downloaded and Android system automatically starts installing it on -the device. However, the installation process will start automatically only if -the user has configured their Settings to allow the installation of apps from -unknown sources.
- -Although it is relatively easy to release your application on your own -website, it can be inefficient. For example, if you want to monetize your -application you will have to process and track all financial transactions -yourself and you will not be able to use Google Play's In-app Billing service -to sell in-app products. In addition, you will not be able to use the Licensing service to -help prevent unauthorized installation and use of your application.
- - -
- - Figure 2. Users must enable the Unknown sources - setting before they can install apps not downloaded from Google Play. -
-Android protects users from inadvertent download and install of apps from -locations other than Google Play (which is trusted). It blocks such installs -until the user opts-in Unknown sources in -Settings > Security, shown in Figure 2. To allow -the installation of applications from other sources, users need to enable the -Unknown sources setting on their devices, and they need to make this -configuration change before they download your application to their -devices.
- -Note that some network providers do not allow users to install -applications from unknown sources.
diff --git a/docs/html/tools/publishing/versioning.jd b/docs/html/tools/publishing/versioning.jd deleted file mode 100644 index 9908d811ca4d6394a63f1b8d22001a180da565b4..0000000000000000000000000000000000000000 --- a/docs/html/tools/publishing/versioning.jd +++ /dev/null @@ -1,184 +0,0 @@ -page.title=Versioning Your Applications -@jd:body - -Versioning is a critical component of your application upgrade and maintenance -strategy. Versioning is important because:
- -The Android system does not use app version information to enforce
-restrictions on upgrades, downgrades, or compatibility of third-party apps. Instead, you (the
-developer) are responsible for enforcing version restrictions within your application or by
-informing users of the version restrictions and limitations. The Android system does, however,
-enforce system version compatibility as expressed by the minSdkVersion attribute in the
-manifest. This attribute allows an application to specify the minimum system API with which it is
-compatible. For more information see Specifying Minimum System API
-Version.
To define the version information for your application, you set attributes in -the application's manifest file. Two attributes are available, and you should -always define values for both of them:
- -android:versionCode — An integer value that represents
-the version of the application code, relative to other versions.
-
-The value is an integer so that other applications can programmatically -evaluate it, for example to check an upgrade or downgrade relationship. You can -set the value to any integer you want, however you should make sure that each -successive release of your application uses a greater value. The system does not -enforce this behavior, but increasing the value with successive releases is -normative.
- -Typically, you would release the first version of your application with
-versionCode set to 1, then monotonically increase the value with each release,
-regardless whether the release constitutes a major or minor release. This means
-that the android:versionCode value does not necessarily have a
-strong resemblance to the application release version that is visible to the
-user (see android:versionName, below). Applications and publishing
-services should not display this version value to users.
- Warning: The greatest possible value for
- android:versionCode is MAXINT (2147483647). However, if
- you upload an app with this value, your app can't ever be updated.
-
android:versionName — A string value that represents the
-release version of the application code, as it should be shown to users.
-The value is a string so that you can describe the application version as a -<major>.<minor>.<point> string, or as any other type of -absolute or relative version identifier.
- -As with android:versionCode, the system does not use this value
-for any internal purpose, other than to enable applications to display it to
-users. Publishing services may also extract the android:versionName
-value for display to users.
You define both of these version attributes in the
-<manifest> element of the manifest file or the Gradle build file. See
-Configuring Gradle Builds.
Here's an example manifest that shows the android:versionCode
-and android:versionName attributes in the
-<manifest> element.
-<?xml version="1.0" encoding="utf-8"?> -<manifest xmlns:android="http://schemas.android.com/apk/res/android" - package="com.example.package.name" - android:versionCode="2" - android:versionName="1.1"> - <application android:icon="@drawable/icon" android:label="@string/app_name"> - ... - </application> -</manifest> -- -
In this example, note that android:versionCode value indicates
-that the current .apk contains the second release of the application code, which
-corresponds to a minor follow-on release, as shown by the
-android:versionName string.
The Android framework provides an API to let applications query the system -for version information about your application. To obtain version information, -applications use the -{@link android.content.pm.PackageManager#getPackageInfo(java.lang.String, int)} -method of {@link android.content.pm.PackageManager PackageManager}.
- -If your application requires a specific minimum version of the Android -platform, or is designed only to support a certain range of Android platform -versions, you can specify those version requirements as API Level identifiers -in the application's manifest file. Doing so ensures that your -application can only be installed on devices that -are running a compatible version of the Android system.
- -To specify API Level requirements, add a <uses-sdk>
-element in the application's manifest, with one or more of these attributes:
android:minSdkVersion — The minimum version
-of the Android platform on which the application will run, specified
-by the platform's API Level identifier. android:targetSdkVersion — Specifies the API Level
-on which the application is designed to run. In some cases, this allows the
-application to use manifest elements or behaviors defined in the target
-API Level, rather than being restricted to using only those defined
-for the minimum API Level.android:maxSdkVersion — The maximum version
-of the Android platform on which the application is designed to run,
-specified by the platform's API Level identifier. Important: Please read the <uses-sdk>
-documentation before using this attribute. When preparing to install your application, the system checks the value of this
-attribute and compares it to the system version. If the
-android:minSdkVersion value is greater than the system version, the
-system aborts the installation of the application. Similarly, the system
-installs your application only if its android:maxSdkVersion
-is compatible with the platform version.
If you do not specify these attributes in your manifest, the system assumes -that your application is compatible with all platform versions, with no -maximum API Level.
- -To specify a minimum platform version for your application, add a
-<uses-sdk> element as a child of
-<manifest>, then define the
-android:minSdkVersion as an attribute.
For more information, see the <uses-sdk>
-manifest element documentation and the API Levels document. For
-Gradle build settings, see
-Configuring Gradle Builds.
Build Tools is a component of the Android SDK required for building Android
- application code. The latest version of these tools is included in the
- SDK starter package and installed in the
- <sdk>/build-tools/ directory.
You should always keep your Build Tools component updated by downloading the latest version - using the Android SDK Manager. By default, - the Android SDK uses the most recent downloaded version of the Build Tools. If your projects - depend on older versions of the Build Tools, the SDK Manager allows you to download and maintain - separate versions of the tools for use with those projects.
- -To use a specific version of the Build Tools in your application project:
- - -
-android {
- ...
- buildToolsVersion "17.0.0"
- ...
-}
-
- The sections below provide notes about releases of the Build Tools. To determine which -revisions of the Build Tools are available in your SDK, refer to the Installed Packages -listing in the Android SDK Manager.
- -
- 
Build Tools, Revision 23.0.3 (March 2016)
-
renderscriptTargetAPI 21+ when using Android
- Plugin for Gradle, Revision 2.1.0 and above .
- Build Tools, Revision 23.0.2 (November 2015)
-
dx tool.
- 
Build Tools, Revision 23.0.1 (October 2015)
-
Fixed issues in the RenderScript tools.
-
- Build Tools, Revision 23.0.0 (August 2015)
-
Added support for the Android 6.0 (API level 23) release.
-
- Build Tools, Revision 22.0.1 (March 2015)
-
Fixed compatibility issues with - RenderScript kernels on - Android 4.4 (API level 19) to Android 4.1 (API level 16) devices.
-
- Build Tools, Revision 22.0.0 (March 2015)
-
Added support for Android 5.1 (API level 22).
-
- Build Tools, Revision 21.1.2 (February 2015)
-
Fixed problem with building data layouts in 32-bit mode.
-
- Build Tools, Revision 21.1.1 (November 2014)
-
Fixed multidex script issues.
-
- Build Tools, Revision 21.1 (October 2014)
-
Added multidex file support for APKs and Jack support to address the 64K method reference - limit.
-
- Build Tools, Revision 21.0.2 (October 2014)
-
Complete updates for Eclipse ADT to solve instability issues on Windows platforms.
-
- Build Tools, Revision 21.0.1 (October 2014)
-
Initial updates for Eclipse ADT on Windows. Please use Revision 21.0.2.
-
- Build Tools, Revision 21.0.0 (October 2014)
-
- Build Tools, Revision 20.0.0 (June 2014)
-
- Build Tools, Revision 19.1.0 (May 2014)
-
zipalign to the Build Tools.aapt to ignore XML files that fail to compile.
- Build Tools, Revision 19.0.3 (March 2014)
-
Fixed an issue with RenderScript support.
- -
- Build Tools, Revision 19.0.2 (February 2014)
-
- Build Tools, Revision 19.0.1 (December 2013)
-
- Build Tools, Revision 19 (October 2013)
-
Added support for Android 4.4 (API level 19) build targets.
- -
- Build Tools, Revision 18.1.1 (September 2013)
-
Fixed several minor build issues.
- -
- Build Tools, Revision 18.1.0 (September 2013)
-
Fixed issue with RenderScript support mode.
- -
- Build Tools, Revision 18.0.1 (July 2013)
-
Added support for Android 4.3 (API level 18) build targets.
- -
- Build Tools, Revision 17 (May 2013)
-
Initial release.
- -- The Android build system uses the Android Plugin for Gradle to support - building Android applications with the Gradle build toolkit. The plugin runs - independent of Android Studio so the plugin and the Gradle build system can - be updated independently of Android Studio. -
- -- When you update Android Studio, you may receive a prompt to automatically - update the Android Plugin for Gradle to the latest available version. You - can choose to accept the update or manually specify a version based on - your project's build requirements. -
- -
- You can specify the Android Plugin for
- Gradle version in either the File > Project
- Structure > Project menu in Android Studio, or
- the top-level build.gradle file. The plugin version applies to
- all modules built in that Android Studio project. The following example sets
- the Android Plugin for Gradle to version 2.1.0 from the
- build.gradle file:
-
-buildscript {
- ...
- dependencies {
- classpath 'com.android.tools.build:gradle:2.1.0'
- }
-}
-
-
- Caution: You should not use dynamic dependencies in version
- numbers, such as 'com.android.tools.build:gradle:2.+'. Using
- this feature can cause unexpected version updates and difficulty resolving
- version differences.
-
- If the specified plugin version has not been downloaded, Gradle downloads it - the next time you build your project or click Tools > - Android > Sync Project with Gradle Files - from the Android Studio main menu. -
- -- When you update Android Studio, you may receive a prompt to automatically - update Gradle to the latest available version. You can choose to accept the - update or manually specify a version based on your project's build - requirements. -
- -
- You can specify the Gradle version in either the File >
- Project Structure > Project menu in
- Android Studio, or by editing the Gradle distribution reference in the
- gradle/wrapper/gradle-wrapper.properties file. The following
- example sets the Gradle version to 2.10 in the
- gradle-wrapper.properties file.
-
-... -distributionUrl = https\://services.gradle.org/distributions/gradle-2.10-all.zip -... -- -
- For a summary of known issues in Android Plugin for Gradle, visit the - Android - Tools Project Site. -
- -
- Android Plugin for Gradle, Revision 2.1.0 (April 2016)
-
- Note: Instant - Run does not currently work with Jack and will be disabled while - using the new toolchain. You only need to use Jack if you are developing - for the N Preview and want to use the supported Java 8 language features. -
-build.gradle file:
-
-
-android {
- ...
- compileOptions {
- incremental false
- }
-}
-
-
- Added support for dexing-in-process which performs dexing within the build
- process rather than in a separate, external VM processes. This not only makes
- incremental builds faster, but also speeds up full builds. The feature is
- enabled by default for projects that have set the Gradle daemon's maximum heap
- size to at least 2048 MB. You can do this by including the following in your
- project's gradle.properties file:
-
-
-org.gradle.jvmargs = -Xmx2048m -- - -
- If you have defined a value for
- javaMaxHeapSize in your module-level build.gradle
- file, you need to set org.gradle.jvmargs to the value of
- javaMaxHeapSize + 1024 MB. For example, if you have set
- javaMaxHeapSize to "2048m", you need to add the following to your
- project's gradle.properties file:
-
-
-org.gradle.jvmargs = -Xmx3072m -- - -
- To disable dexing-in-process, add the following code to your module-level
- build.gradle file:
-
-
-android {
- ...
- dexOptions {
- dexInProcess false
- }
-}
-
-
-
- Android Plugin for Gradle, Revision 2.0.0 (April 2016)
-
maxProcessCount to control how many slave dex processes can be
- spawned concurrently. The following code, in the module-level
- build.gradle file, sets the maximum number of concurrent processes
- to 4:
-
-android {
- ...
- dexOptions {
- maxProcessCount = 4 // this is the default value
- }
-}
-
- build.gradle file:
-
-
-android {
- ...
- buildTypes {
- debug {
- minifyEnabled true
- useProguard false
- }
- release {
- minifyEnabled true
- useProguard true // this is a default setting
- }
- }
-}
-
- resources.txt
- file located in the same folder as the Proguard log files.
- minSdkVersion is set to 18 or higher, APK signing uses
- SHA256.
- - Note: The Android keystore provider no - longer supports - DSA keys on Android 6.0 (API level 23) and higher. -
- -
- Android Plugin for Gradle, Revision 1.5.0 (November 2015)
-
build.gradle file that uses the
- plugin:
-android {
- dataBinding {
- enabled = true
- }
-}
-
- .class files before they’re
- converted to .dex files. The Transform API simplifies injecting custom class
- manipulations while offering more flexibility regarding what you can manipulate. To insert a
- transform into a build, create a new class implementing one of the Transform
- interfaces, and register it with android.registerTransform(theTransform) or
- android.registerTransform(theTransform, dependencies). There’s no need to
- wire tasks together. Note the following about the Transform API:javac/dx code path does.dex getter from the ApplicationVariant class.
- You can't access the Dex task through the variant API anymore because it’s now
- accomplished through a transform. There's
- currently no replacement for controlling the dex process.com.android.support:multidex-instrumentation
- dependency.ANDROID_SERIAL environment variable when installing or running tests.android:minSdkVersion attribute of 20 or lower in the
- <uses-sdk> element in the app manifest. You can set PNG densities by
- using the generatedDensities property in the defaultConfig or
- productFlavor sections of a build.gradle file.android.jar, which the plugin generates only
- once and uses for unit testing. Multiple modules, such as app and
- lib, now share it. Delete $rootDir/build to regenerate it. android:compileSdkVersion attribute in the experimental library
- plugin.
- Android Plugin for Gradle, Revision 1.3.1 (August 2015)
-
createDebugCoverageReport build task. archiveBaseName property
- in the build.gradle build> file. Invalid ResourceType
- lint warning caused by parameter method
- annotation lookup when running
- lint outside of Android Studio.
- Android Plugin for Gradle, Revision 1.3.0 (July 2015)
-
com.android.build.threadPoolSize property to control
- the Android task thread pool size from the gradle.properties file
- or the command line. The following example sets this property to 4.
---Pcom.android.build.threadPoolSize=4 --
LICENSE and LICENSE.txt
- files from APKs. To include these files in an APK, remove these files from the
- packagingOptions.excludes property in the build.gradle file.
- For example:
-
-android {
- packagingOptions.excludes = []
- }
-
- sourceSets task to inspect the set of all available source sets. flavor1 and flavorA with the Debug build type,
- the test source sets are:
- Android tests already recognized multi-flavor source folders.
javac on main and test sources, even if the useJack
- property is set to true in your build file. -./gradlew connectedCheck \ - -Pandroid.testInstrumentationRunnerArguments.size=medium \ - -Pandroid.testInstrumentationRunnerArguments.class=TestA,TestB --
build.gradle file. For example:
-
-android {
- aaptOptions {
- additionalParameters "--custom_option", "value"
- }
-}
-
- targetProjectPath and targetVariant properties to set the APK
- path and target variant.
- Note: A test APK module does not support product - flavors and can only target a single variant. Also, Jacoco is not supported yet.
-@{applicationId} placeholder in the
- manifest merger settings.
- Instead, use a different placeholder, such as @{libApplicationId} and
- provide a value for it if you want to include application Ids in the archive library.
- Android Plugin for Gradle, Revision 1.2.0 (April 2015)
-
unitTestVariants property so unit test variants
- can be manipulated using the build.gradle file.
- unitTest.all code block under testOptions to
- configure customized tasks for unit test. The following sample code shows how to add
- unit test configuration settings using this new option:
-
-android {
- testOptions {
- unitTest.all {
- jvmArgs '-XX:MaxPermSize=256m' // Or any other gradle option.
- }
- }
-}
-
- mockable-android.jar file.
- testProguardFile property to apply
- ProGuard files when minifying a test APK.
- timeOut property to the adbOptions code block
- for setting the maximum recording time for
- Android Debug Bridge screen recording.
-
- Android Plugin for Gradle, Revision 1.1.3 (March 2015)
-
- Android Plugin for Gradle, Revision 1.1.2 (February 2015)
-
archivesBaseName setting in the build.gradle file.
- Android Plugin for Gradle, Revision 1.1.1 (February 2015)
-
android.getBootClasspath() method to return a value.
- Android Plugin for Gradle, Revision 1.1.0 (February 2015)
-
android.jar file that is
- compatible with popular mocking frameworks, for example Mockito. testDebug, testRelease, and
- testMyFlavorDebug when using product flavors. src/test/java/,
- src/testDebug/java/, src/testMyFlavor/java/.
- build.gradle file for declaring test-only
- dependencies, for example, testCompile 'junit:junit:4.11',
- testMyFlavorCompile 'some:library:1.0'.
- Note: Test-only dependencies are not currently compatible - with Jack (Java Android Compiler Kit).
-android.testOptions.unitTests.returnDefaultValues option to
- control the behaviour of the mockable android.jar. Test in test task names with AndroidTest.
- For example, the assembleDebugTest task is now
- assembleDebugAndroidTest task. Unit test tasks still have UnitTest
- in the task name, for example assembleDebugUnitTest. provided and package scopes.
- Note: These scopes are incompatible with AAR - (Android ARchive) packages and will cause a build with AAR packages to fail.
-anyDpi
- resource qualifier
- in resource merger.
- Android Plugin for Gradle, Revision 1.0.1 (January 2015)
-
Note: This version of the Android Plugin for Gradle is - not compatible with Gradle 2.4 and higher.
-extractReleaseAnnotations module.
- (Issue 81638).Disable passing the
- --no-optimize setting to the Dalvik Executable (dex) bytecode.
- (Issue 82662).targetSdkVersion less than 16.
- Android Plugin for Gradle, Revision 1.0.0 (December 2014)
-
Note: This version of the Android Plugin for Gradle is - not compatible with Gradle 2.4 and higher.
-The Android SDK is composed of individual packages that may undergo -an update at their own schedule, so some have their own set of release notes. You can -find information about some of the packages in this section, including the core SDK Tools and the latest SDK Platforms. Release notes are also available -for Android developer tools, such as -Android Studio and the -Android Plugin for Gradle. -
diff --git a/docs/html/tools/revisions/platforms.jd b/docs/html/tools/revisions/platforms.jd deleted file mode 100644 index b3941aed6a683d97e1c741e7b3573529c6b46435..0000000000000000000000000000000000000000 --- a/docs/html/tools/revisions/platforms.jd +++ /dev/null @@ -1,1374 +0,0 @@ -page.title=SDK Platforms Release Notes - -@jd:body - -This document provides release information about the SDK Platform packages required -for app development. If you want details about the features and APIs added in each Android -version, instead read the highlights in the About -section.
- -To compile your application against a particular version of Android, you must use the -SDK Manager to download and install the SDK -Platform for that release. If you want to test your application on an emulator, you must also -download at least one System Image for that Android version.
- - -Each platform release includes system images that support a specific processor architecture, -such as ARM EABI, Intel x86 or MIPS. Platform releases also include a system image that contains -Google APIs. The SDK Manager lists available -platform system images under each platform version header, for example:
- -To determine what revisions of an Android platform you have installed, refer to the -Packages listing in the Android -SDK Manager.
- -Important: To download the most recent Android -system components from the Android SDK Manager, you must first update the SDK Tools to the -most recent release and restart the SDK Manager. If you do not, the latest Android system -packages may not be available for download.
- - -
- Revision 2 (November 2015)
-
Fixed bugs in the layout rendering library used by Android Studio.
-Dependencies:
-
- Revision 1 (August 2015)
-
Initial release for Android 6.0 (API level 23). For more information, see the - M Preview API Overview.
-Dependencies:
-
- Revision 1 (March 2015)
-
Initial release for Android 5.1 (API level 22). For more information, see the - Android 5.1 API Overview.
-Dependencies:
-
- Revision 2 (December 2014)
-
Updated layouts in the Support Library and fixed various issues.
-Dependencies:
-
- Revision 1 (October 2014)
-
Initial release for Android 5.0 (API level 21). For more information, see the - Android 5.0 API Overview.
-Dependencies:
-The platform includes the following new device definitions for use in creating - Android Virtual Devices in the AVD Manager:
- -
- Revision 2 (October 2014)
-
Updated the rendering library.
- -Dependencies:
-
- Revision 1 (June 2014)
-
Initial release for Android Wear.
-Dependencies:
-The platform includes the following device definitions for use in creating Android Virtual - Devices in the AVD Manager:
- -
- Revision 2 (December 2013)
-
Maintenance release. The system version is 4.4.2. For more information, see the - Android 4.4 API Overview.
-
- Revision 1 (October 2013)
-
Initial release. The system version is 4.4. For more information, see the - Android 4.4 API Overview.
-
- Revision 4 (March 2014)
-
This release includes - Google Play services version 4.3, - allowing you to test your application in an emulator using the latest Google Play services.
- -
- Revision 3 (February 2014)
-
This release includes - Google Play services version 4.2.42, - allowing you to test your application in an emulator using the latest Google Play services.
- -
- Revision 2 (December 2013)
-
This release includes - Google Play services version 4.0.33.
- -
- Revision 1 (October 2013)
-
Initial release. This release includes - Google Play services version 4.0.30. -
- -
- Revision 2 (August 2013)
-
Maintenance update. The system version is 4.3.
-
- Revision 1 (July 2013)
-
Initial release. The system version is 4.3.
-
- Revision 3 (September 2013)
-
Maintenance update. This release includes - Google Play services version 3.2.65. -
- -
- Revision 2 (August 2013)
-
Maintenance update. This release includes - Google Play services version 3.2.25. -
- -
- Revision 1 (July 2013)
-
Initial release. This release includes - Google Play services version 3.1.58.
- -
- Revision 2 (February 2013)
-
Maintenance update. The system version is 4.2.2.
-
- Revision 1 (November 2012)
-
Initial release. The system version is 4.2.
-The platform includes the following device definitions for use in creating Android Virtual -Devices in the AVD Manager:
- -
- Revision 3 (October 2012)
-
Maintenance update. The system version is 4.1.2.
-
- Revision 2 (July 2012)
-
Maintenance update. The system version is 4.1.1.
-
- Revision 1 (June 2012)
-
Initial release. The system version is 4.1.0.
-The downloadable platform includes the following emulator skins:
- -To test your application on an emulator that represents the Nexus 7 tablet device, you can create an AVD with -the new WXGA800-7in skin. For best performance, make sure to enable graphics acceleration in the -emulator configuration.
- - - - - - - - - - - - - - -
- Revision 3 (March 2012)
-
Maintenance update. The system version is 4.0.4.
-Note: This system image includes support for emulator -hardware graphics acceleration when used with SDK Tools r17 or higher. -(more info)
-
- Revision 2 (January 2012)
-
Maintenance update. The system version is 4.0.3.
-
- Revision 1 (December 2011)
-
Initial release. The system version is 4.0.3.
-The downloadable platform includes the following emulator skins:
- -
- Android 4.0, Revision 2 (December 2011)
-
Maintenance update. The system version is 4.0.2.
-
- Android 4.0, Revision 1 (October 2011)
-
Initial release. The system version is 4.0.1.
-The downloadable platform includes the following emulator skins:
- -To test your application on an emulator that represents the latest Android device, you can create -an AVD with the new WXGA720 skin (it's an xhdpi, normal screen device). Note that the emulator -currently doesn't support the new on-screen navigation bar for devices without hardware navigation -buttons, so when using this skin, you must use keyboard keys Home for the Home button, -ESC for the Back button, and F2 or Page-up for the Menu button.
- -However, due to performance issues in the emulator when running high-resolution screens such as -the one for the WXGA720 skin, we recommend that you primarily use the traditional WVGA800 skin -(hdpi, normal screen) to test your application.
- - - - - - - - - - - - - -
- Android 3.2, Revision 1 (July 2011)
-
The downloadable platform includes the following emulator skin:
- -For more information about how to develop an application that displays -and functions properly on all Android-powered devices, see Supporting Multiple -Screens.
- - - - - - - - - - - - - - - - - - -
- Android 3.1, Revision 3 (July 2011)
-
Requires SDK Tools r12 or -higher.
-Improvements to the platform's rendering library to support the visual layout editor in the ADT -Eclipse plugin. This revision allows for more drawing features in ADT and fixes several -bugs in the previous rendering library. It also unlocks several editor features that were added in -ADT 12.
-
- Android 3.1, Revision 2 (May 2011)
-
Requires SDK Tools r11 or -higher.
-Fixes an issue with the visual layout editor rendering library that prevented Android 3.1 from -running in ADT.
-
- Android 3.1, Revision 1 (May 2011)
-
Requires SDK Tools r11 or -higher.
-The downloadable platform includes the following emulator skin:
- -For more information about how to develop an application that displays -and functions properly on all Android-powered devices, see Supporting Multiple -Screens.
- - - - - - - - - - - -
- Android 3.0, Revision 2 (July 2011)
-
Requires SDK Tools r12 or -higher.
-Improvements to the platform's rendering library to support the visual layout editor in the ADT -Eclipse plugin. This revision allows for more drawing features in ADT and fixes several -bugs in the previous rendering library. It also unlocks several editor features that were added in -ADT 12.
-
- Android 3.0, Revision 1 (February 2011)
-
Requires SDK Tools r10 or higher.
-The downloadable platform includes the following emulator skin:
- -
- Android 2.3.4, Revision 1 (May 2011)
-
Requires SDK Tools r11 or higher.
-The downloadable platform includes a set of emulator skins that you can use -for modeling your application in different screen sizes and resolutions. The -emulator skins are:
- -
- Android 2.3.3, Revision 2 (July 2011)
-
Requires SDK Tools r12 or -higher.
-Improvements to the platform's rendering library to support the visual layout editor in the ADT -Eclipse plugin. This revision allows for more drawing features in ADT and fixes several -bugs in the previous rendering library. It also unlocks several editor features that were added in -ADT 12.
-
- Android 2.3.3, Revision 1 (February 2011)
-
Requires SDK Tools r9 or higher.
-The downloadable platform includes a set of emulator skins that you can use -for modeling your application in different screen sizes and resolutions. The -emulator skins are:
- -
- Android 2.3, Revision 1 (December 2010)
-
Requires SDK Tools r8 or higher.
-The downloadable platform includes a set of emulator skins that you can use -for modeling your application in different screen sizes and resolutions. The -emulator skins are:
- -
- Android {@sdkPlatformVersion}, Revision 3 (July 2011)
-
Requires SDK Tools r12 or -higher.
-Improvements to the platform's rendering library to support the visual layout editor in the ADT -Eclipse plugin. This revision allows for more drawing features in ADT and fixes several -bugs in the previous rendering library. It also unlocks several editor features that were added in -ADT 12.
-
- Android {@sdkPlatformVersion}, Revision 2 (July 2010)
-
Requires SDK Tools r6 or higher.
-
- Android {@sdkPlatformVersion}, Revision 1 (May 2010)
Requires SDK Tools r6 or higher.
-Adds support for building with Android library projects. See SDK -Tools, r6 for information.
-The downloadable platform includes a set of emulator skins that you can use -for modeling your application in different screen sizes and resolutions. The -emulator skins are:
- -Android Studio is the official IDE for Android development, and with a single download includes -everything you need to begin developing Android apps:
- -For an introduction to Android Studio, read the -Android Studio guide.
- -Periodic updates are pushed to Android Studio without requiring you to update your Android -project. To manually check for updates, select Help > Check for update (on Mac, -select Android Studio > Check for updates).
- - -The sections below provide notes about successive releases of -Android Studio, as denoted by revision number.
- - -
- Android Studio v2.1.0 (April 2016)
-
The primary changes in this update provide support for development with the -Android N Preview.
- -The Android N platform adds support for Java 8 language features, which -require a new experimental compiler called Jack. The latest version of Jack is -currently supported only in Android Studio 2.1. So if you want to use Java 8 -language features, you need to use Android Studio 2.1 to build your app.
- -Note: Instant Run -is disabled when you enable the Jack compiler because they currently are not -compatible.
- -Although Android Studio 2.1 is now stable, the Jack compiler is still
-experimental and you must enable it with the jackOptions
-property in your build.gradle file.
Other than the changes to support the N Preview, Android Studio 2.1 -includes minor bug fixes and the following enhancements:
-For other build enhancements, including incremental Java compilation - and dexing-in-process, update your Android Plugin for -Gradle to version 2.1.0.
-
- Android Studio v2.0.0 (April 2016)
-
- Note: If you are developing for the N Developer Preview, you - should use Android Studio 2.1 Preview. Android Studio 2.0 does not support - all the features required to target the N Preview. To learn more, read about - how to properly set up your - developer environment for the N Preview. -
- -- Instant Run: -
- -
- Note: Instant Run is supported only when you deploy the
- debug build variant, use Android Plugin for
- Gradle version 2.0.0 or higher, and configure your app's module-level
- build.gradle file for minSdkVersion 15 or higher.
- For the best performance, configure your app for minSdkVersion
- 21 or higher.
-
New additions to Lint:
-Additional Improvements:
-
- Android Studio v1.5.1 (December 2015)
-
Fixes and enhancements:
-description manifest attributes by configuration.
- Issue: 194705
- % operator for data binding. Issue: 194045
-
- Android Studio v1.5.0 (November 2015)
-
Fixes and enhancements:
-AndroidManifest.xml file. It can also
- generate code to help you integrate with the
- App Indexing API
- in an activity in a Java file. A deep link testing feature
- helps you verify that a specified deep link can launch an app. In the General
- tab of the Run/Debug Configurations dialog, you can specify deep link launch
- options. You can also test App Indexing API calls in an activity by using the Android Monitor
- logcat display. The Android lint tool now has warnings for
- certain issues involving deep links and the App Indexing API.
- lint checks for Android TV and Android Auto to give you
- immediate, actionable feedback in Android Studio, along with several quick fixes. For example,
- for Android TV, it can report and provide a quick fix for permissions, unsupported hardware,
- uses-feature element, and missing banner issues. For Android Auto, it can
- validate the correct usage in the descriptor file referred from your
- AndroidManifest.xml file, report if there isn't an intent filter for the
- MediaBrowserService class, and identify certain voice actions issues.
- lint checks for insecure broadcast receivers,
- SSLCertificateSocketFactory and HostnameVerifier class uses, and
- File.setReadable() and File.setWritable() calls. It also detects
- invalid manifest resource lookups, especially for resources that vary by configuration.
-
- Android Studio v1.4.1 (October 2015)
-
Fixes and enhancements:
-android:required attribute was ignored in the manifest.
- Issue: 187665
-
- Android Studio v1.4.0 (September 2015)
-
Fixes and enhancements:
-appcompat Support Library
- for backwards compatibility.
-
- Android Studio v1.3.2 (August 2015)
-
Fixes and enhancements:
-
- Android Studio v1.3.1 (August 2015)
-
Fixes and enhancements:
-
- Android Studio v1.3.0 (July 2015)
-
Fixes and enhancements:
-@RequiresPermission, @CheckResults, and
- @MainThread. Note: The standalone SDK Manager is still available from - the command line, but is recommended for use only with standalone SDK - installations.
finger command in the emulator console to simulate
- fingerprint
- authentication. <public> resource declaration to designate library
- resources as
- public and private
- resources.
- Note: Requires - Android Plugin for Gradle - version 1.3 or higher.
- Android Studio v1.2.2 (June 2015)
-
Fixes and enhancements:
-
- Android Studio v1.2.1 (May 2015)
-
Fixes and enhancements:
-
- Android Studio v1.2.0 (April 2015)
-
Fixes and enhancements:
-See - What's New in IntelliJ - for a complete description of the new features and enhancements.
- -res/drawable-280dpi/ folder.
-
- Android Studio v1.1.0 (February 2015)
-
Various fixes and enhancements:
-res/mipmap folders for
- density-specific launcher icons. These res/mipmap folders replace the
- res/drawable
- folders for launcher icons. xxxhdpi launcher icon. lint checks
- for region and language combinations, launcher icons, resource names, and other common
- code problems.
- Android Studio v1.0.1 (December 2014)
-
Various fixes and enhancements:
-
- Android Studio v1.0 (December 2014)
-
Initial release of Android Studio.
-
- Android Studio v0.8.14 (October 2014)
-
See - tools.android.com - for a full list of changes.
-
- Android Studio v0.8.6 (August 2014)
-
See tools.android.com for a full list of changes.
-
- Android Studio v0.8.0 (June 2014)
-
Added support for Android Wear projects.
-See tools.android.com for a full list of changes.
-
- Android Studio v0.5.2 (May 2014)
-
- Android Studio v0.4.6 (March 2014)
-
- Android Studio v0.4.2 (Jan 2014)
-
- Android Studio v0.3.2 (Oct 2013)
-
- Android Studio v0.2.x (July 2013)
-
Caution: This new version is not backwards compatible. - When opening a project that uses an older version of the plug-in, Studio will show an error - stating Gradle <project_name> project refresh failed.
-The updated Gradle plug-in includes the following changes:
-variant.packageApplication or variant.zipAlignAll Gradle plugin release notes are available are here: http://tools.android.com/tech-docs/new-build-system.
-
- Android Studio v0.1.x (May 2013)
-
- - -
If you encounter problems in Android Studio, look at the following page -for possible resolutions to known issues: http://tools.android.com/knownissues.
- - - -Android Development Tools (ADT) is a plugin for the Eclipse IDE -that extends the capabilities of Eclipse to let you quickly set up new Android -projects, create an application UI, add packages based on the Android -Framework API, debug your applications using the Android SDK tools, and even -export signed (or unsigned) {@code .apk} files in order to distribute your application.
- -Note: -If you have been using Eclipse with ADT, be aware that Android Studio is now the official IDE -for Android, so you should migrate to Android Studio to receive all the -latest IDE updates. For help moving projects, -see Migrating to Android -Studio.
- -Note that -before you can install or use ADT, you must have compatible versions of both the -Eclipse IDE and the Android SDK installed. For details, make sure to read Installing the Eclipse -Plugin.
- - -For information about the features provided by the ADT plugin, such as code -editor features, SDK tool integration, and the graphical layout editor (for drag-and-drop layout -editing), see the Android Developer Tools -document.
- - -The sections below provide notes about successive releases of -the ADT Plugin, as denoted by revision number.
- -For a summary of all known issues in ADT, see http://tools.android.com/knownissues.
- - -
- ADT 23.0.7 (August 2015)
-
- ADT 23.0.6 (March 2015)
-
- ADT 23.0.4 (October 2014)
-
- ADT 23.0.3 (August 2014)
-
NullPointerException warning dialog
- when a valid SDK was not configured. (Issue
- 73313)
- ADT 23.0.2 (July 2014)
-
- ADT 23.0.0 (June 2014)
-
- ADT 22.6.3 (April 2014)
-
When you create an Android Wear virtual device in the AVD manager, a target API Level - lower than 19 may be selected by default. Make sure you select the target API Level 19 - when creating Android Wear virtual devices.
-
- ADT 22.6.2 (March 2014)
-
Changed the URL for the Android Developer Tools update site to require HTTPS.
-Note: If you are - updating ADT, make sure - you use HTTPS in the URL for the Android Developer Tools update site.
-NullPointerException after
- removing a virtual device that was created using the Android Wear
- system image. (Issue 67588)drawable-* directories instead of those from the
- drawable-large-* directories.
- ADT 22.6.1 (March 2014)
-
Fixed a problem with virtual devices created using ADT 22.3 or earlier.
-If you created an Android Virtual Device using ADT 22.3 or earlier, the - AVD may be listed as broken in the AVD Manager in 22.6.1. To fix - this problem, select the virtual device on the AVD Manager and click - Repair.
-lint script.When you create an Android virtual device using the Nexus 5 device definition, - you must enable the Use Host GPU option, otherwise the virtual device - will not start.
-
- ADT 22.6.0 (March 2014)
-
Added support for Java 7 language features like multi-catch, try-with-resources,
- and the diamond operator. These features require version 19 or higher
- of the Build Tools. Try-with-resources requires minSdkVersion
- 19; the rest of the new language features require
- minSdkVersion 8 or higher.
To use the new language features after installing ADT 22.6.0, ensure - that you run Eclipse on JDK 7 and change your application project settings - to use JDK 7.
-SecureRandom
- vulnerability.checkPermission use the return
- value.
- ADT 22.3.0 (October 2013)
-
- ADT 22.2.1 (September 2013)
-
- ADT 22.2 (September 2013)
-
- ADT 22.0.5 (July 2013)
-
- ADT 22.0.4 (July 2013)
-
- ADT 22.0.1 (May 2013)
-
- ADT 22.0.0 (May 2013)
-
- ADT 21.1.0 (February 2013)
-
- ADT 21.0.1 (December 2012)
-
- ADT 21.0.0 (November 2012)
-
- ADT 20.0.3 (August 2012)
-
- ADT 20.0.2 (July 2012)
-
- ADT 20.0.1 (July 2012)
-
- ADT 20.0.0 (June 2012)
-
- ADT 18.0.0 (April 2012)
-
- ADT 17.0.0 (March 2012)
-
- ADT 16.0.1 (December 2011)
-
- ADT 16.0.0 (December 2011)
-
- ADT 15.0.1 (November 2011)
-
.jar files.bin/ folder for library projects are refreshed. This ensures that parent projects pick up changes in library projects.res/ folders are checked in library projects. This ensures that all res folders are properly included
- even if Eclipse is not aware of them due to refresh issues.aapt from running when editing certain XML files.
- ADT 15.0.0 (October 2011)
-
- ADT 14.0.0 (October 2011)
-
default.properties to project.properties and
- build.properties to ant.properties. ADT automatically
- renames these files, if necessary, when you open a project in Eclipse.javac from bin/ to bin/classes
- in Eclipse.id) and no longer
- run once for each library project.For a complete overview of the build system changes and what you need to do to support them, -see the Android Tools Project -site.
-
- ADT 12.0.0 (July 2011)
-
wrap_content and match_parent.
- In LinearLayout, sizes are mapped to weights instead of pixel widths.
- (more info).
- ADT 11.0.0 (June 2011)
-
More information about tool changes are available on the Android Tools Project Site.
-
- ADT 10.0.1 (March 2011)
-
- ADT 10.0.0 (February 2011)
-
gen/ directory) and
- bytecode (in the res/raw/ directory) from your .rs files..java files quickly show all the matches in the project
- and allows you jump to specific items such as string translations or onClick handlers
- (details).<merge> layouts, as well as layouts with gesture overlays
- (details).
- ADT 9.0.0 (January 2011)
-
R.id.main) to the corresponding XML declaration, or from XML attributes (such as
- @string) to the corresponding resource definition, or from manifest XML
- registrations to activities and services.<include>
- and <merge>
- tags (Details).match_parent when added to a vertical {@link android.widget.LinearLayout}
- or a default image is added to an {@link android.widget.ImageButton}.<include> tag, double-clicking on the
-
- <include> element edits the referenced layout in the context of the
- current layout. Additionally, when editing a layout that is included by other layouts,
- you can quickly change between context layouts, by right clicking in the editor and choosing
- Show included in.... This feature is only available in Honeycomb.debuggable=true was not set in the Android manifest.
- ADT 8.0.1 (December 2010)
-
This version of ADT is designed for use with SDK Tools r8. If you haven't -already installed SDK Tools r8 into your SDK, use the Android SDK Manager to do -so.
- -Also see the recent release notes for 8.0.0, below.
-
- ADT 8.0.0 (December 2010)
-
This version of ADT is designed for use with SDK Tools r8. If you haven't -already installed SDK Tools r8 into your SDK, use the Android SDK Manager to do -so.
- -debuggable attribute in the Android Manifest.
- Incremental builds automatically insert debuggable="true", but if you perform
- "export signed/unsigned application package", ADT does not insert it.
- If you manually set debuggable="true" in the manifest file, then release builds will
- actually create a debug build (it does not remove it if you placed it there).
proguard.config
- property in the default.properties file that points to a ProGuard config file.android.jar source and javadoc can now be configured.
- ADT 0.9.9 (September 2010)
-
ADT 0.9.9 replaces ADT 0.9.8 and is designed for use with SDK Tools r7 -and later. ADT 0.9.9 includes the ADT 0.9.8 features as well as an important -bugfix, so we recommend that you upgrade as soon as possible. If you haven't -already installed SDK Tools r7 into your SDK, use the Android SDK Manager to do -so.
- ADT 0.9.8 (September 2010)
-
ADT 0.9.8 is now deprecated. Please use ADT 0.9.9 instead.
src/. There is now support for any number of source folders,
-with no name restriction. They can even be in subfolder such as
-src/java. If you are already working with library projects created
-in ADT 0.9.7, see Migrating
-library projects to ADT 0.9.8 for important information about moving
-to the new ADT environment.car/desk, night/notnight and
-navexposed/navhidden.
- ADT 0.9.7 (May 2010)
-
The ADT Plugin now supports the use of library projects during -development, a capability that lets you store shared Android application -code and resources in a separate development project. You can then reference the -library project from other Android projects and, at build time, the tools -compile the shared code and resources as part of the dependent applications. -More information about this feature is available in the Creating and Managing Projects document.
-If you are not developing in Eclipse, SDK Tools r6 provides the equivalent library -project support through the Ant build system.
-
- ADT 0.9.6 (March 2010)
-
This version of ADT is designed for use with SDK Tools r5 and later. Before -updating to ADT 0.9.6, we highly recommend that you use the Android SDK Manager to install SDK -Tools r5 into your SDK.
default.properties outside of Eclipse will now
-automatically update the project.
- ADT 0.9.5 (December 2009)
-
This version of ADT requires features provided in SDK Tools r4 or higher. If you install -ADT 0.9.5, which is highly recommended, you should use the Android SDK -Manager to download the latest SDK Tools into your SDK. For more information, -see Exploring the SDK.
-
- ADT 0.9.4 (October 2009)
-
This version of ADT requires features provided in SDK Tools r3 or higher. If you install -ADT 0.9.4, which is highly recommended, you should use the Android SDK -Manager to download the latest SDK Tools into your SDK. For more information, -see Exploring the SDK.
-The NDK is a toolset that allows you to implement parts - of your app using native-code languages such as C and C++. Typically, good use cases for the NDK - are CPU-intensive applications such as game engines, signal processing, and physics simulation. -
- -Before downloading the NDK, you should understand that the NDK - will not benefit most apps. As a developer, you need to balance its benefits - against its drawbacks. Notably, using native code on Android - generally does not result in a noticable performance improvement, - but it always increases your app complexity. In general, you should only use the NDK - if it is essential to your app—never because you simply prefer to program in C/C++. - When examining whether or not you should develop in native code, think about your requirements and - see if the Android framework APIs provide the functionality that you need.
- - - NDK Documentation and Downloads diff --git a/docs/html/tools/sdk/preview/features.jd b/docs/html/tools/sdk/preview/features.jd deleted file mode 100644 index 2bdb0f42fbcfd5d45a362afff0f49e7e8241f8be..0000000000000000000000000000000000000000 --- a/docs/html/tools/sdk/preview/features.jd +++ /dev/null @@ -1,9 +0,0 @@ -excludeFromSuggestions=true -@jd:body - - - -You should have already been redirected by your browser. Please go to the -Android 3.0 Platform.
\ No newline at end of file diff --git a/docs/html/tools/sdk/preview/index.jd b/docs/html/tools/sdk/preview/index.jd deleted file mode 100644 index 713730efb7c6f4bcc35a2a607f9ae062550eb95b..0000000000000000000000000000000000000000 --- a/docs/html/tools/sdk/preview/index.jd +++ /dev/null @@ -1,4 +0,0 @@ -sdk.redirect=true -page.template=sdk -excludeFromSuggestions=true -@jd:body diff --git a/docs/html/tools/sdk/preview/installing.jd b/docs/html/tools/sdk/preview/installing.jd deleted file mode 100644 index d248b67704ee9402b7fe84f5b743879bd35f0f59..0000000000000000000000000000000000000000 --- a/docs/html/tools/sdk/preview/installing.jd +++ /dev/null @@ -1,9 +0,0 @@ -excludeFromSuggestions=true -@jd:body - - - -You should have already been redirected by your browser. Please go to -Installing the SDK.
\ No newline at end of file diff --git a/docs/html/tools/sdk/preview/requirements.jd b/docs/html/tools/sdk/preview/requirements.jd deleted file mode 100644 index b62ee05005071404fcee5e41a479b723dcf4b1b4..0000000000000000000000000000000000000000 --- a/docs/html/tools/sdk/preview/requirements.jd +++ /dev/null @@ -1,9 +0,0 @@ -excludeFromSuggestions=true -@jd:body - - - -You should have already been redirected by your browser. Please go to the -SDK System Requirements.
\ No newline at end of file diff --git a/docs/html/tools/sdk/preview/upgrading.jd b/docs/html/tools/sdk/preview/upgrading.jd deleted file mode 100644 index 3b9069623b906dcb13a984ddca0bf823e26544e2..0000000000000000000000000000000000000000 --- a/docs/html/tools/sdk/preview/upgrading.jd +++ /dev/null @@ -1,9 +0,0 @@ -excludeFromSuggestions=true -@jd:body - - - -You should have already been redirected by your browser. Please go to -the Android SDK.
\ No newline at end of file diff --git a/docs/html/tools/sdk/tools-notes.jd b/docs/html/tools/sdk/tools-notes.jd deleted file mode 100644 index f72d3f3e943f13fa000519c19505f90c35a324b5..0000000000000000000000000000000000000000 --- a/docs/html/tools/sdk/tools-notes.jd +++ /dev/null @@ -1,2320 +0,0 @@ -page.title=SDK Tools Release Notes -excludeFromSuggestions=true -@jd:body - -SDK Tools is a downloadable component for the Android SDK. It includes the -complete set of development and debugging tools for the Android SDK. It is included -with Android Studio.
- -If you are already using the SDK and you want to update to the latest version -of the SDK Tools, use the SDK Manager to get the -update.
- - -The sections below provide notes about successive releases of -the SDK Tools, as denoted by revision number. To determine what revision of the SDK -Tools you are using, refer to the "Installed Packages" listing in the Android SDK Manager.
- -- For a summary of all known issues in SDK Tools, visit the Android Tools - Project Site. -
- -
- SDK Tools, Revision 25.0.0
- (April 2016)
-
- SDK Platform-tools, Revision 23.1.0
- (December 2015)
-
- SDK Tools, Revision 24.4.1 (October 2015)
-
- SDK Tools, Revision 24.4.0 (October 2015)
-
- SDK Tools, Revision 24.3.4 (August 2015)
-
- SDK Tools, Revision 24.3.3 (June 2015)
-
- SDK Tools, Revision 24.3.2 (June 2015)
-
- SDK Tools, Revision 24.3.1 (June 2015)
-
root/ and lib/ folders. Caution: This release is known to contain issues which - prevent builds from completing. We strongly recommend that you update to SDK Tools 24.3.2 - as soon as possible.
-
- SDK Tools, Revision 24.3.0 (June 2015)
-
Caution: This release is known to contain issues which - prevent builds from completing. We strongly recommend that you update to SDK Tools 24.3.2 - as soon as possible.
-
- SDK Tools, Revision 24.2.0 (May 2015)
-
- SDK Tools, Revision 24.1.2 (February 2015)
-
- SDK Tools, Revision 24.0.2 (December 2014)
-
- SDK Tools, Revision 24.0.1 (December 2014)
-
- SDK Tools, Revision 24.0.0 (December 2014)
-
- SDK Tools, Revision 23.0.5 (October 2014)
-
- SDK Tools, Revision 23.0.4 (October 2014)
-
- SDK Tools, Revision 23.0.2 (July 2014)
-
.bat files that were missing.proguard-android.txt file that was missing.lombok-ast-0.2.2.jar file to lombok-ast.jar,
- which should allow running lint from the command line.
- SDK Tools, Revision 23.0.0 (June 2014)
-
- SDK Tools, Revision 22.6.4 (June 2014)
-
- SDK Tools, Revision 22.6.3 (April 2014)
-
When you create an Android Wear virtual device in the AVD manager, a target API Level - lower than 19 may be selected by default. Make sure you select the target API Level 19 - when creating Android Wear virtual devices.
-
- SDK Tools, Revision 22.6.2 (March 2014)
-
NullPointerException after
- removing a virtual device that was created using the Android Wear
- system image. (Issue 67588)
- SDK Tools, Revision 22.6.1 (March 2014)
-
Fixed a problem with virtual devices created using ADT 22.3 or earlier.
-If you created an Android Virtual Device using ADT 22.3 or earlier, the - AVD may be listed as broken in the AVD Manager in 22.6.1. To fix - this problem, select the virtual device on the AVD Manager and click - Repair.
-lint script.When you create an Android virtual device using the Nexus 5 device definition, - you must enable the Use Host GPU option, otherwise the virtual device - will not start.
-
- SDK Tools, Revision 22.6 (March 2014)
-
The command line lint script (tools\lint.bat on
- Windows platforms, tools/lint on other platforms) and the
- lint target on ant builds fail with the following
- error:
Exception in thread "main" java.lang.NoClassDefFoundError:
- lombok/ast/AstVisitor
As a temporary workaround, rename the file
- tools\lib\lombok-ast-0.2.2.jar to
- tools\lib\lombok-ast.jar.
- We will release an updated version of the tools with a fix for
- this issue as soon as possible.
minSdkVersion
- 19; the rest of the new language features require
- minSdkVersion 8 or higher.SecureRandom
- vulnerability.checkPermission use the return value.
- SDK Tools, Revision 22.3 (October 2013)
-
- SDK Tools, Revision 22.2.1 (September 2013)
-
- SDK Tools, Revision 22.2 (September 2013)
-
- SDK Tools, Revision 22.0.5 (July 2013)
-
- SDK Tools, Revision 22.0.4 (July 2013)
-
- SDK Tools, Revision 22.0.1 (May 2013)
-
- SDK Tools, Revision 22 (May 2013)
-
- SDK Tools, Revision 21.1 (February 2013)
-
- SDK Tools, Revision 21.0.1 (December 2012)
-
renderscript.target = 17- Previously, the RenderScript compilation target was tied to the - {@code android:minSdkVersion} setting in the manifest. - (Issue 40487) -
- SDK Tools, Revision 21 (November 2012)
-
dex.force.jumbo=true
- SDK Tools, Revision 20.0.3 (August 2012)
-
- SDK Tools, Revision 20.0.1 (July 2012)
-
- SDK Tools, Revision 20 (June 2012)
-
- SDK Tools, Revision 19 (April 2012)
-
Note: This update of SDK Tools is only available through -the Android SDK Manager. Use this tool to -download and install this update.
- -
- SDK Tools, Revision 18 (April 2012)
-
Important: To download the new Android - 4.0 system components from the Android SDK Manager, you must first update the - SDK tools to revision 14 or later and restart the Android SDK Manager. If you do not, - the Android 4.0 system components will not be available for download.
- -
- SDK Tools, Revision 17 (March 2012)
-
Important: To download the new Android - 4.0 system components from the Android SDK Manager, you must first update the - SDK tools to revision 14 or later and restart the Android SDK Manager. If you do not, - the Android 4.0 system components will not be available for download.
- -Note: Use the Android SDK Manager to download and -install x86 system images. Android x86 system images are not available for all API levels.
-
- SDK Tools, Revision 16 (December 2011)
-
Important: To download the new Android - 4.0 system components from the Android SDK Manager, you must first update the - SDK tools to revision 14 or later and restart the Android SDK Manager. If you do not, - the Android 4.0 system components will not be available for download.
- -
- SDK Tools, Revision 15 (October 2011)
-
Important: To download the new Android - 4.0 system components from the Android SDK Manager, you must first update the - SDK tools to revision 14 or later and restart the Android SDK Manager. If you do not, - the Android 4.0 system components will not be available for download.
--wipe-data argument.ant test
- (Issue 20979).android update project
- (Issue 20535).
- SDK Tools, Revision 14 (October 2011)
-
Important: To download the new Android - 4.0 system components from the Android SDK Manager, you must first update the - SDK tools to revision 14 and restart the Android SDK Manager. If you do not, - the Android 4.0 system components will not be available for download.
-default.properties to project.properties and
- build.properties to ant.properties. Any existing
- projects that you build with Ant must be updated with the android update project
- command.build.xml file to support improvements to the
- build system and added and modified Ant commands to support these changes. For a list of Ant
-commands, see the
-Ant Command
-Reference.id) and no longer
- run once for each library project.For a complete overview of the build system changes and what you need to do to support them, -see the Android Tools Project -site.
-
- SDK Tools, Revision 13 (September 2011)
-
If you are developing in Eclipse with ADT, note that this version of SDK Tools is designed for use with -ADT 12.0.0 and later. If you haven't already, we highly recommend updating your ADT Plugin to 12.0.0.
- -If you are developing outside Eclipse, you must have Apache -Ant 1.8 or later.
- -dex step) when paths have spaces.
- SDK Tools, Revision 12 (July 2011)
-
If you are developing in Eclipse with ADT, note that this version of SDK Tools is designed for use with -ADT 12.0.0 and later. If you haven't already, we highly recommend updating your ADT Plugin to 12.0.0.
- -If you are developing outside Eclipse, you must have Apache -Ant 1.8 or later.
- -
- SDK Tools, Revision 11 (May 2011)
-
If you are developing in Eclipse with ADT, note that this version of SDK Tools is designed for use with -ADT 10.0.1 and later. If you haven't already, we highly recommend updating your ADT Plugin to 10.0.1.
- -If you are developing outside Eclipse, you must have Apache -Ant 1.8 or later.
- -
- SDK Tools, Revision 10 (February 2011)
-
If you are developing in Eclipse with ADT, note that this version of SDK Tools is -designed for use with ADT 10.0.0 and later. After installing SDK Tools r10, we -highly recommend updating your ADT Plugin to 10.0.0.
- -If you are developing outside Eclipse, you must have Apache -Ant 1.8 or later.
- -gen directory) and
- bytecode (in the res/raw directory) from your native .rs files
- SDK Tools, Revision 9 (January 2011)
-
If you are developing in Eclipse with ADT, note that this version of SDK Tools is -designed for use with ADT 9.0.0 and later. After installing SDK Tools r9, we -highly recommend updating your ADT Plugin to 9.0.0.
- -If you are developing outside Eclipse, you must have Apache -Ant 1.8 or later.
- -If you are upgrading to SDK Tools r9 from SDK Tools r7 or earlier, the default installed location
-for the adb tool has changed from <SDK>/tools/adb to
-<SDK>/platform-tools/adb. This means that you should
-add the new location to your PATH and modify any custom build scripts to
-reference the new location. Copying the adb executable from the new
-location to the old is not recommended, since subsequent updates to the SDK
-Tools will delete the file.
proguard.cfg, now ignores the following classes:
- java.encoding, java.source,
- and java.target properties.javac Ant task is now UTF-8.draw9patch from running.hierarchyviewer and ddms to support
- the new location of adb.
- SDK Tools, Revision 8 (December 2010)
-
If you are developing in Eclipse with ADT, note that this version of SDK Tools is -designed for use with ADT 8.0.0 and later. After installing SDK Tools r8, we -highly recommend updating your ADT Plugin to 8.0.0.
- -If you are developing outside Eclipse, you must have Apache -Ant 1.8 or later.
- -Also note that SDK Tools r8 requires a new SDK component called
-Platform-tools. The new Platform-tools component lets all SDK platforms
-(Android 2.1, Android 2.2, and so on) use the same (latest) version of build
-tools such as adb, aapt, aidl, and
-dx. To download the Platform-tools component, use the Android SDK
-Manager, as described in Exploring the
-SDK
If you are upgrading to SDK Tools r8 from an earlier version, note that the
-the default installed location for the adb tool has changed from
-<SDK>/tools/adb to
-<SDK>/platform-tools/adb. This means that you should
-add the new location to your PATH and modify any custom build scripts to
-reference the new location. Copying the adb executable from the new
-location to the old is not recommended, since subsequent updates to the SDK
-Tools will delete the file.
android:debuggable attribute to the
-<application> tag in the manifest — the build tools add
-the attribute automatically. In Eclipse/ADT, all incremental builds are assumed
-to be debug builds, so the tools insert android:debuggable="true".
-When exporting a signed release build, the tools do not add the attribute. In
-Ant, a ant debug command automatically inserts the
-android:debuggable="true" attribute, while ant release
-does not. If android:debuggable="true" is manually set, then
-ant release will actually do a debug build, rather than a release
-build.android tool — the build tools
-then automatically run ProGuard against the project sources during the build.
-For more information, see the ProGuard
-documentation. java.encoding,
-java.source, and java.target (default values are
-"ascii", "1.5", and "1.5", respectively).
- SDK Tools, Revision 7 (September 2010)
-
If you are developing in Eclipse with ADT, note that this version of SDK Tools is -designed for use with ADT 0.9.8 and later. After installing SDK Tools r7, we -highly recommend updating your ADT Plugin to 0.9.8.
--pre-build, -pre-compile, and
--post-compile.android -h update sdk
-for more information.
- SDK Tools, Revision 6 (May 2010)
-
If you are developing in Eclipse with ADT, note that this version of SDK Tools is -designed for use with ADT 0.9.7 and later. After installing SDK Tools r6, we -highly recommend updating your ADT Plugin to 0.9.7.
-The SDK Tools now support the use of library projects during -development, a capability that lets you store shared Android application -code and resources in a separate development project. You can then reference the -library project from other Android projects and, at build time, the tools -compile the shared code and resources as part of the dependent applications. -More information about this feature is available in the Creating and Managing Projects document.
-If you are developing in Eclipse, ADT -provides the equivalent library project support.
-
- SDK Tools, Revision 5 (March 2010)
-
layoutopt.bat to execute correctly on Windows.
- SDK Tools, Revision 4 (December 2009)
-
This version of SDK Tools is compatible with ADT 0.9.5 and later, but not -compatible with earlier versions. If you are developing in Eclipse with ADT, you -must update your ADT plugin to version 0.9.5 or higher if you -install SDK Tools r4 in your SDK.
- SDK Tools, Revision 3 (October 2009)
-
This version of SDK Tools is compatible with ADT 0.9.4 and later, but not -compatible with earlier versions. If you are developing in Eclipse with ADT, you -must update your ADT plugin to version 0.9.4 or higher if you -install SDK Tools r3 in your SDK.
-android create test-project and android update
-test-project commands to allow for greater flexibility in the location of the
-main and test projects.The SDK Tools r3 package includes layoutopt, a new command-line
-tool that helps you optimize your layout hierarchies. When run against your
-layout files, the tool analyzes their hierarchies and notifies you of
-inefficiencies and other potential issues. The tool also provides simple
-solutions for the issues it finds. For usage, see layoutopt.
- Android Studio provides a number of coding features to assist with writing and building your - app. These tools help you write code faster and improve quality. -
- -This document describes the differences between Eclipse ADT and Android Studio, including project - structure, build system, debugging, and application packaging. This guide is intended to help you - transition to using Android Studio as your development environment.
- -Eclipse provides workspaces as a common area for grouping related projects, configurations, and
-settings. In Android Studio, each instance of Android Studio contains a top-level project with one
-or more app modules. Each app module folder contains the equivalent to an Eclipse
-project, the complete source sets for that module, including {@code src/main} and
-{@code src/androidTest} directories, resources, build file, and the Android manifest. In general,
-to update and build your app you modify the files under each module's
-{@code src/main} directory for source code updates, the gradle.build file for
-build specification, and the files under {@code src/androidTest} directory for test case creation.
You can also customize the view of the project files in Android Studio to focus on specific -aspects of your app development:
- -The following table shows the general mapping of the Eclipse ADT project structure and file -locations to Android Studio.
- -- Table 1. Project structure mapping.
- -| Eclipse ADT | -Android Studio | -
|---|---|
| Workspace | -Project | -
| Project | -Module | -
| Project-specific JRE | -Module JDK | -
| Classpath variable | -Path variable | -
| Project dependency | -Module dependency | -
| Library Module | -Library | -
AndroidManifest.xml |
- app/src/main/AndroidManifest.xml |
-
assets/ |
- app/src/main/assets |
-
res/ |
- app/src/main/res/ |
-
src/ |
- app/src/main/java/ |
-
tests/src/ |
- app/src/androidTest/java/ |
-
Table 2 shows Eclipse ADT and Android Studio project views.
- -- Table 2. Comparing project views.
-| Eclipse ADT | -Android Studio Project View | -Android Studio Android View | -
|---|---|---|
 |
-  |
-  |
-
Note: Multiple instances of Android Studio can be used to develop -independent projects.
- - - - -Android Studio and Gradle-based builds support
- build variants,
-which are combinations of productFlavor and buildTypes, to customize
-your build outputs. To support these custom builds, several elements in the
-AndroidManifest.xml file are now properties in the defaultConfig and
-productFlavors blocks in the build.gradle file. The import process
-copies these manifest settings to the properties in the build.gradle file.
-These properties overwrite the settings in any other manifest files as shown in table 3.
- Table 3. Manifest and Gradle property settings.
-| Manifest Setting | -build.gradle Setting | -
|---|---|
<uses-sdk -
|
- -
|
-
<manifest
- package (Required in the default manifest file.) -
|
- -
|
-
Although these settings may no longer appear in the default app manifest file, they are still -valid manifest entries and may still appear in manifests from older projects, imported projects, -dependencies, and libraries.
- -The package element 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.
Note: When multiple manifests are present in your app, for
-example a library manifest and a src/main/ manifest, the build process combines
-the manifest settings into a single merged manifest based on the manifest priority and
-manifest merge settings. For more information about the manifest merge process and merge settings,
-see
- Manifest Merger.
With 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. This field is populated in the
-build file as part of the migration process.
-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"
- }
- ...
-
-
-Note: The applicationId is specified only in your
-build.gradle file, and not in the AndroidManifest.xml file.
Build variants
-enable you to uniquely identify different
-packages for each product flavor and build type. The application ID in the build type setting can
-be added as a suffix to the ID specified for the product flavors. The following example adds the
-.debug suffix to the application ID of the pro and free
-product flavors:
-productFlavors {
- pro {
- applicationId = "com.example.my.pkg.pro"
- }
- free {
- applicationId = "com.example.my.pkg.free"
- }
-}
-
-buildTypes {
- debug {
- applicationIdSuffix ".debug"
- }
-}
-....
-
-
-
-
-During the import process, Android Studio imports the current Eclipse ADT dependencies and
-downloads any project libraries as Android Studio modules. The dependency declarations are added to
-the build.gradle file. The declarations include a
-dependency scope, such as
-compile, to specify in which builds the dependency is included.
The following example shows how to add an external library JAR dependency so it's included in -each compile:
- -
-dependencies {
- compile files('libs/*.jar')
-}
-
-android {
- ...
-}
-
-
-Note: Android Studio supports the Android ARchive (AAR) format -for the distribution of Android library projects as dependencies. For more information, see -Configuring Gradle Builds.
- - -The import process replaces any well-known source libraries, binary libraries, and JAR files -that have known Maven coordinates with Maven dependencies, so you no longer need to -maintain these dependencies manually.
- -Android Studio enables access to Maven, JCenter, and Ivy repositories with the
-repositories block in the build.gradle as a shortcut to specifying
-the URL of the repository.
-
-
If there are required repositories not declared in the build.gradle file, first add
-the repository to the repositories block, and then declare the dependencies in a way
-that Maven, JCenter, or Ivy declare their artifacts. The following example shows how to add the
-Maven repository with the guava 11.0.2 dependency using the mavenCentral() property:
-repositories {
- mavenCentral()
-}
-
-android {
- ...
-}
-
-dependencies {
- compile 'com.google.guava:guava:11.0.2'
- instrumentationtestCompile 'com.squareup.fast-android:1:0.4'
-}
-
-
-
-The Android Studio project created during the import process can also re-use any -dependencies on other components. These components can be external binary packages or other -Gradle projects. If a dependency has dependencies of its own, -those dependencies are also included in the new Android Studio project.
- - -Note: If there were references to Eclipse ADT workspace library
-files in the project.properties or .classpath files
-that were not imported from the Eclipse project, you can now add dependencies to these library files
-in the build.gradle file. For more information, see
-Configuring Gradle Builds.
Android Studio supports compilation scopes to customize which dependencies get -included in each build, for example assigning different dependencies to different - build variants.
- -This list shows the Android Studio scope names and definitions:
- -compile packageAndroidTestCompileAndroidTestRunPackagebuildTypeCompile productFlavorCompile Note: Dependencies for library projects must be added with the
-compile scope.
With the Gradle-based DSL, you can also add custom
-dependency scopes, such as betaCompile file('libs/protobug.jar') to define a beta
-build dependency.
The scope and compilation configuration in the build file determine the -components compiled into the app, added to the compilation classpath, and packaged in the final -APK file. Based on the dependency and compilation scope, different compilation configurations -can be specified to include the dependencies and classpaths, for example:
- -compile - for the main application. androidTestCompile - for the test application. debugCompile - for the debug buildType application.releaseCompile - for the release buildType application. Note: Because it’s not possible to build an APK that does not
-have an associated buildType, the APK built from your app is always configured with
-at least two dependency and compile configurations: compile and
-debugCompile.
Unlike Eclipse ADT, by default Android Studio does not compile your code when there are changes. -Use the File > Settings > Build, Execution, Deployment Compiler option -to enable automatic compilation.
- - - -Android Studio imports the Eclipse ADT Ant-based
-build tasks and converts the tasks to Gradle-based build tasks.
-These new build tasks include the
-main assemble task and at least two outputs based on the default build types:
-a debug APK and a
-release APK. Each of these build tasks has its own Android build system anchor task
-to facilitate building them independently:
assembleassembleDebugassembleReleaseIn Android Studio, you can view all the supported build tasks in the -Gradle project tab.
- -With the Gradle-based build system, Android Studio uses a -Gradle wrapper to fully integrate the -Android Plugin for Gradle. The Android Plugin for Gradle also -runs independent of Android Studio. This means that with Android Studio build system your build -output is always the same, whether you build your Android apps from Android Studio, from the -command line on your machine, or on machines where Android Studio is not installed (such as -continuous integration servers).
- -Unlike Eclipse ADT with dependent plugin and build updates, the build.gradle
-files allow you to customize the build settings for each Android Studio module and build variant,
-so the build versions can be set independently, and are not dependent on the Android Studio
-or build tools versions. This makes it easy to maintain and build legacy apps along with your
-current app, using build variants to generate different APKs from the same app modules, but
-built with different build versions and build chains.
For more details about the Android Studio build system, see -Build System Overview.
- -In contrast with the XML statements in Ant build files, the Android build system and
-Gradle DSL provide a declarative build language so you can
-easily extend the Gradle-based build process beyond the typical XML build tasks. For example,
-this build file shows how to define a custom function to inject a dynamic versionCode
-in build outputs:
-def getVersionCode) {
- def code = …
- return code
-}
-
-android {
- defaultConfig {
- versionCode getVersionCode()
- …
- }
-}
-
-
-This example shows how to append debug to your package and version names used in the
-debug build variant of your app:
-android {
- buildTypes {
- debug {
- packageNameSuffix ‘.debug’
- versionNameSuffix ‘-DEBUG’
- }
- beta {
- …
- }
- }
-}
-
-
-
-You can also use the declarative DSL in the Android build system to generate custom build
-versions, for example a debuggable version of your release APK. This examples adds the
-debuggable true property to the release build type in the
-build.gradle file to build an identical debuggable version of the release package.
-android {
- buildTypes {
- debugRelease.initWith(buildTypes.release)
- debugRelease {
- debuggable true
- packageNameSuffix '.debugrelease'
- signingConfig signingConfigs.debug
- }
-
- }
- sourceSets.debugRelease.setRoot('src/release')
-}
-
-
-
-
-
-
-
-Using code inspection tools such as lint is a -standard part of Android development. Android Studio extends -lint support with additional -lint checks and supports Android -annotations that -allow you to help detect more subtle code problems, such as null pointer exceptions and resource -type conflicts. Annotations are added as metadata tags that you attach to variables, parameters, -and return values to inspect method return values, passed parameters, and local variables and -fields.
- -For more information on enabling lint inspections -and running lint, -see Improving Your Code with lint. -For more information about using annotations, see -Improving your Code with -Annotations.
- -In addition to code inspection, Android Studio provides an integrated -memory and CPU monitor view so you -can more easily monitor your app's performance and memory usage to track CPU usage, find -deallocated objects, locate memory leaks, and track the amount of memory the connected device is -using.
- - - -After importing and building your app, Android Studio supports several -Gradle-based properties to help you minimize your app's -resource utilization.
- - -In Android Studio, resource shrinking enables the automatic removal of unused resources from -your packaged app and also removes resources from library dependencies if the resources are not -actually used by your app.
- -Use the shrinkResources attribute in the buildType block in your
-build.gradle file to enable resource shrinking. For example, if your application is
-using Google Play services
-to access Google Drive functionality, and you are not currently using
-Google+ Sign In, then
-this setting removes the various drawable assets for the SignInButton buttons.
Note: Resource shrinking works in conjunction with code shrinking -tools, such as ProGuard.
- -To enable resource shrinking, update the buildTypes block in the
-build.gradle file to include minifyEnabled true,
-shrinkResources true, and proguardFiles settings as shown in the
-following example Gradle build file.
-android {
- ...
-
- buildTypes {
- release {
- minifyEnabled true
- shrinkResources true
- proguardFiles getDefaultProguardFile('proguard-android.txt'),
- 'proguard-rules.pro'
- }
- }
-}
-
-
-
-
-Use the resConfig attribute in your build.gradle file
-to filter the locale resources included in your packaged app. This filtering can be especially
-useful when library dependencies such as appcompat-v7 and other libraries such as
-google-play-services_lib are included in your app.
The following example limits the locale resources to three language settings: en,
-de, and es:
-apply plugin: 'android'
-
-android {
- compileSdkVersion 22
- buildToolsVersion "22.0.1"
-
- defaultConfig {
- minSdkVersion 8
- targetSdkVersion 22
- versionCode 1
- versionName "1.0"
- resConfigs "en", "de", "es" //Define the included language resources.
- }
-...
-
-
-
-
-
-You can also use the resConfig build setting to limit the bundled resources
-in any resource folder. For example, you could also add resConfigs
-settings for density folders, such as mdpi or hdpi to limit the drawable
-resources that are packaged in your APK file. This example limits the app's
-bundled resources to medium-density (MDPI) and high-density (HDPI) resources.
-android {
- defaultConfig {
- ...
- resConfigs "mdpi", "hdpi"
- }
-}
-
-
-For more information about screen and resource densities, see
-Supporting Multiple Screens
-and Supporting Different Densities.
-
-
-With Android Studio, identical resources, such as copies of launcher and menu icons, may end up -in different resource folders throughout your app. To reduce resource duplication and improve -the performance of your app, Android Studio merges resources with an identical resource name, type, -and qualifier into a single resource and passes the single, merged resource to the Android Asset -Packaging Tool (AAPT) for distribution in the APK file.
- -The resource merging process looks for identical resources in the following /res/
-folders:
src/main/ src/productFlavor/ src/buildType/ Identical resources are merged in the following low to high priority order:
--dependencies --> src/main/ --> src/productFlavor/ --> src/buildType/ -- -
For example, if the res/ic_menu.png file is included in both the
-src/main/res/ and src/productFlavor/res/ folders, the resources are merged
-so only the file with the higher priority, in this case the src/productFlavor/res/
-file, is included in the APK file.
Note: Identical resources in the same source set are not merged
-and instead generate a resource merge error. This can happen if the sourceSet property
-in the build.gradle file is used to define multiple source sets, for example
-src/main/res/ and src/main/res2/, and these folders contain identical
-resources.
Based on the imported Eclipse ADT app settings, Android Studio automatically sets up your app -signing and maintains any ProGuard settings.
- -If your app used a debug certificate in Eclipse ADT, Android Studio continues to reference that
-certificate. Otherwise, the debug configuration uses the Android Studio generated
-debug keystore, with a known password and a default key with a known password located in
-$HOME/.android/debug.keystore. The debug build type is set to use this
-debug SigningConfig automatically when you run or debug your project
-from Android Studio.
In release mode, Android Studio applies the release certificate used in Eclipse ADT. If no
-release certificate was located during the import process, add the release signing configuration to
-the build.gradle file or use the Build > Generate Signed APK menu
-option to open the Generate Signed APK Wizard. For more information about signing your app, see
-Signing Your Applications.
If the ProGuard option is specified in the
-project.properties file in the Eclipse ADT project, Android Studio imports the
-ProGuard files and adds the
-ProGuard settings to the
-build.gradle file. ProGuard is
-supported through the minifyEnabled property as shown in this example.
-android {
- buildTypes {
- release {
- minifyEnabled true
- proguardFile getDefaultProguardFile('proguard-android.txt')
- }
- }
-
- productFlavors {
- flavor1 {
- }
- flavor2 {
- proguardFile 'some-other-rules.txt'
- }
- }
-}
-
-
-
-
-
-
-While Eclipse ADT uses the Android Support -Library and Google Play services Library, Android Studio replaces these libraries during the -import process with the Android Support Repository and Google Repository to maintain -compatible functionality and support new Android features. Android Studio adds these dependencies -as Maven dependencies using the known Maven coordinates, so these dependencies do not require -manual updates.
- -In Eclipse, in order to use a -Support Library, you must modify your -project's classpath dependencies within your development environment for each -Support Library you want to use. In -Android Studio, you no longer need to copy library sources into your -own projects, you can simply declare a dependency and the library is automatically downloaded and -merged into your project. This includes automatically merging in resources, manifest entries, -ProGuard exclusion rules, and custom lint rules -at build time.
- -Android Studio also supports binary library Android ARchives (AARs). AARs are a library project's -main output as a combination of compiled code (as a jar file and/or native .so files) and -resources (manifest, res, assets).
- - -The Android build system introduces the use of the applicationId attribute to
-uniquely identify application packages for publishing. The application ID is set in the
-android section of the build.gradle file.
The applicationId is specified only in your build.gradle file, and
-not in the
-AndroidManifest.xml file. The Gradle-based build system enables you
-to uniquely identify different packages for each build variant based on product flavors and build
-types. You can also add the applicationIdSuffix property to the build type in the
-build.gradle file to append an identifier, such as '.debug', to the application ID
-generated for each product flavor.
Android Studio provides several levels of update and maintenance to help you keep Android Studio -up-to-date based on your code-level preference:
- -Eclipse ADT supports version control through the use of plugins, such as the EGit and Subversive -plug-ins.
- -Android Studio supports a variety of version control systems (Git, GitHub, CVS, Mercurial, -Subversion, and Google Cloud) so version control operations can continue from within Android -Studio.
- -After importing your Eclipse ADT app into Android Studio, use the -Android Studio VCS menu options to enable VCS support for the desired version control -system, create a repository, import the new files into version control, and perform other version -control operations.
- -Note: You can also use the -File > Setting > Version Control menu option to setup and modify the version -control settings.
- -A number of Android Studio files are typically not added to version control as these are
-temporary files or files that get overwritten with each build. These files are listed in
-an exclusion file, such as .gitignore, for the project and each app module.
-Typically, the following files are excluded from version control:
Android Studio is the official IDE for Android app development, based on -IntelliJ IDEA. On top of IntelliJ's powerful code editor and -developer tools, Android Studio offers even more features that enhance your -productivity when building Android apps, such as:
- - -This page provides an introduction to basic Android Studio features. For -more detailed guides to using Android Studio, start by browsing pages in the -Workflow section.
- -For a summary of the latest changes, see the Android Studio Release Notes.
- - - -
-Figure 1. The project files in Android -view.
-Each project in Android Studio contains one or more modules with source code -files and resource files. Different types of modules include:
- -By default, Android Studio displays your project files in the -Android project view, as shown in figure 1. -This view is organized by modules to -provide quick access to the key source files of your -project.
- -All the build files are visible at the top level -under Gradle Scripts and each app module -contains the following three elements:
-The Android project structure on disk differs -from this flattened representation. To see the actual file structure of the -project, select Project from the Project -drop-down (in figure 1, it's showing as Android).
- -You can also customize the view of the project files to focus on specific -aspects of your app development. For example, selecting the -Problems view of your project displays links to the source -files containing any recognized coding and syntax errors, such as missing an -XML element closing tag in a layout file.
- -For more information, see -IntelliJ project organization -and Managing Projects.
- - -Android Studio uses Gradle as the foundation of the build system, with -more Android-specific capabilities provided by the Android Plugin for -Gradle. This build system -runs 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:
- -The flexibility of Gradle 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.
- - - - -Android Studio assists you in debugging and improving the -performance of your code, including inline debugging and -performance analysis tools.
- - -Use inline debugging to enhance your code walk-throughs in the debugger view -with inline verification of references, expressions, and variable values. -Inline debug information includes:
- -To enable inline debugging, in the Debug window click the Settings icon
-
and select the
-check box for Show Values In Editor.
Android Studio provides a memory and CPU monitor view so you can more easily monitor your -app's performance and memory usage to track CPU usage, find deallocated objects, locate memory -leaks, and track the amount of memory the connected device is using. With your app running on a -device or emulator, click the Android tab in the lower left corner of the -runtime window to launch the Android runtime window. Click the Memory or -CPU tab.
- -
- Figure 2. Monitor memory and CPU usage.
- -When you're monitoring memory usage in Android Studio you can, at the same time, initiate -garbage collection and dump the Java heap to a heap snapshot in an Android-specific HPROF binary -format file. The HPROF viewer displays classes, instances of each class, and a reference tree to -help you track memory usage and find memory leaks.
- -
- Figure 3. HPROF viewer with heap dump.
- -To create a snapshot of the Android app heap memory, click the
-Dump Java Heap icon ()
-in the Memory Monitor. Android Studio creates the heap snapshot file with the filename
-Snapshot-yyyy.mm.dd-hh.mm.ss.hprof
-in the Captures tab. Double-click the heap snapshot file to open the HPROF viewer.
To convert a heap dump to standard HPROF format in Android Studio, right-click a heap -snapshot in the Captures view and select Export to standard .hprof.
- - - -Android Studio allows you to track memory allocation as it monitors memory use. Tracking memory -allocation allows you to monitor where objects are being allocated when you perform certain actions. -Knowing these allocations enables you to adjust the method -calls related to those actions to optimize your app's performance and memory use.
- -
- Figure 4. Allocation tracker.
- -For information about tracking and analyzing allocations, see - Memory Monitor. -
- - -The Android SDK tools, such as Systrace, -logcat, and -Traceview, generate performance and debugging -data for detailed app analysis.
- -To view the available generated data files, click Captures in the left
-corner of the runtime window. In the list of the generated files, double-click a file to view
-the data. Right-click any .hprof files to convert them to a standard
-.hprof file format.
In Android Studio, the configured lint
-and other IDE inspections run automatically whenever you compile your program. In addition to the
-configured {@code lint} checks, additional
-IntelliJ code inspections and annotation validation run to streamline code
-review.
Android Studio enables several lint checks
-to ensure:
-
Cipher.getInstance() is used with safe valuesHovering over an inspection error displays the full issue explanation inline for easy error -resolution. There is also a helpful hyperlink at the end of the error message for additional -error information.
- -With Android Studio, you can also run {@code lint} inspections for a specific build variant, or
-for all build variants. You can configure the {@code lint} inspections that run by adding a
-lintOptions property to the Android settings in the build.gradle
-file.
-android {
- lintOptions {
- // set to true to turn off analysis progress reporting by lint
- quiet true
- // if true, stop the gradle build if errors are found
- abortOnError false
- // if true, only report errors
- ignoreWarnings true
- }
-
-
-
-You can also manage inspection profiles and configure inspections within Android Studio. -Choose File > Settings >, expand the Editor options, -and select Inspections. -The Inspection Configuration page appears with the supported inspections.
-
Figure 5. Configure inspections.
- -Note: To change the behavior of specific -inspection notifications, change the inspection severity, for example from warning -to error.
- - -To manually run inspections in Android Studio, choose Analyze > Inspect Code. -The Inspections Scope dialog appears so you can specify the desired inspection profile and scope.
- - -For more information, see -Improving Your Code with {@code lint} -and lint tool.
- - - -Android Studio supports annotations for variables, parameters, and return values to help you -catch bugs, such as null pointer exceptions and resource type conflicts. The -Android SDK Manager packages -the {@link android.support.annotation Support-Annotations} library -in the Android Support Repository for use with Android -Studio. Android Studio validates the configured annotations during code inspection.
- -To add annotations to your code in Android Studio, first add a dependency for the -{@link android.support.annotation Support-Annotations} library:
- icon to include a
- Library dependency.support-annotations and
- click Ok. The build.gradle file is updated with the support-annotations
-dependency.
You can also manually add this dependency to your build.gradle file, as shown in
-the following example.
-dependencies {
- compile fileTree(dir: 'libs', include: ['*.jar'])
- compile 'com.android.support:appcompat-v7:22.0.0'
- compile 'com.android.support:support-annotations:22.0.0'
-}
-
-
-
-
-A nullability analysis scans the contracts throughout the method hierarchies in your code to -detect:
-The analysis then automatically inserts the appropriate null annotations in the detected -locations.
- -To run a nullability analysis in Android Studio, -select the Analyze > Infer Nullity -menu option. Android Studio inserts the Android -{@link android.support.annotation.Nullable @Nullable} and -{@link android.support.annotation.NonNull @NonNull} annotations in detected locations -in your code. After running a null analysis, it's good practice to verify the injected -annotations.
- -Note: The nullability analysis may insert the IntelliJ
-
-@Nullable and
-
-@NotNull annotations instead of the Android null annotations. When running
-a null analysis, manually search and replace any IntelliJ annotations or include
-com.intellij:annotations:12.0 as a compile dependency in your
-build.gradle file. This example includes the IntelliJ annotations 12.0 library as a
-dependency in the build.gradle file:
-
-
-dependencies {
- compile fileTree(dir: 'libs', include: ['*.jar'])
- compile 'com.android.support:appcompat-v7:22.0.0'
- compile 'com.android.support:support-annotations:22.0.0'
- compile 'com.intellij:annotations:12.0'
-}
-
-
-
-
-
-You can also manually add nullability, resource, and enumerated annotations throughout your code
-to perform validations for a variety of reference values, such as
-R.string resources,
-Drawable
-resources,
-Color resources,
-and enumerated constants.
Run Analyze > Inspect Code to validate the configured annotations.
- -For a complete list of the supported annotations, either use the auto-complete feature to display
-the available options for the import android.support.annotation statement or
-view the contents of the
-{@link android.support.annotation Support-Annotations}
-library.
For more details about Android annotations, see -Improving Code Inspection with Annotations. - -
When you build and run your app with Android Studio, you can view adb and device log messages -(logcat) by clicking Android at the bottom of the window.
- -If you want to debug your app with the
-Android Debug Monitor, you can launch it by
-clicking Monitor
-
-in the toolbar. The Debug Monitor is where you can find the complete set of
-DDMS tools for profiling your app,
-controlling device behaviors, and more. It also includes the Hierarchy Viewer tools to help
- optimize your layouts.
Android Studio provides wizards and templates that verify your system -requirements, such as the Java Development Kit (JDK) and available RAM, and configure default -settings, such as an optimized default Android Virtual Device (AVD) emulation and updated system -images. This document describes additional configuration settings you may want to use to -customize your use of Android Studio.
- -For specific documentation about emulator and device setup and use, see -Managing Virtual Devices, -Using Hardware Devices, and -OEM USB Drivers.
- - -After the initial Android Studio installation and setup, use the -SDK Manager to verify and update the tools, -platforms, packages, and other components used by your apps. You can also use the -File > Settings > -Appearance & Behavior > System Settings > -Updates to configure the SDK Manager to automatically prompt whenever updates are -available.
- -Note: You can also customize the build.gradle file
-so each app uses a specific build chain and compilation options. For more information see,
-Configuring Gradle Builds.
Android Studio provides four update channels to keep Android Studio up-to-date based on your -code-level preference: -
By default, Android Studio uses the Stable channel. Use -File > Settings > Appearance & Behavior System Settings > Updates to change your -channel setting.
- - - -Proxies serve as intermediary connection points between HTTP clients and web servers that add -security and privacy to internet connections.
- -To support running Android Studio behind a firewall, set the proxy settings for the -Android Studio IDE and the SDK Manager. Use the Android Studio IDE HTTP Proxy settings page to set -the HTTP proxy settings for Android Studio. The SDK Manager has a separate HTTP Proxy settings -page.
- -When running the Android Plugin for Gradle from the command line or on machines where -Android Studio is not installed, such as continuous integration servers, set the proxy settings -in the Gradle build file.
- -Note: After the initial installation of the Android Studio bundle, -Android Studio can run with internet access or off-line. However, Android Studio requires an -internet connection for Setup Wizard synchronization, 3rd-party library access, access to remote -repositories, Gradle initialization and synchronization, and Android Studio version updates.
- - -Android Studio supports HTTP proxy settings so you can run Android Studio behind a firewall or -secure network. To set the HTTP proxy settings in Android Studio:
-For application-specific HTTP proxy settings, set the proxy settings in the -{@code build.gradle} file as required for each application module.
-
-apply plugin: 'com.android.application'
-
-android {
- ...
-
- defaultConfig {
- ...
- systemProp.http.proxyHost=proxy.company.com
- systemProp.http.proxyPort=443
- systemProp.http.proxyUser=userid
- systemProp.http.proxyPassword=password
- systemProp.http.auth.ntlm.domain=domain
- }
- ...
-}
-
-
-
-
-For project-wide HTTP proxy settings, set the proxy settings in the
-gradle/gradle.properties file.
-# Project-wide Gradle settings. -... - -systemProp.http.proxyHost=proxy.company.com -systemProp.http.proxyPort=443 -systemProp.http.proxyUser=username -systemProp.http.proxyPassword=password -systemProp.http.auth.ntlm.domain=domain - -systemProp.https.proxyHost=proxy.company.com -systemProp.https.proxyPort=443 -systemProp.https.proxyUser=username -systemProp.https.proxyPassword=password -systemProp.https.auth.ntlm.domain=domain - -... -- - -
For information about using Gradle properties for proxy settings, see the - Gradle User Guide.
- -Note: When using Android Studio, the settings in the Android -Studio IDE HTTP proxy settings page override the HTTP proxy settings in the -gradle.properties file.
- - - -SDK Manager proxy settings enable proxy internet access for Android package and library -updates from SDK Manager packages.
- -To set the SDK Manager settings for proxy internet access, start the SDK Manager and open the -SDK Manager page.
- -The Android SDK Manager page appears. Enter the settings and click Apply.
- - - diff --git a/docs/html/tools/studio/studio-features.jd b/docs/html/tools/studio/studio-features.jd deleted file mode 100644 index 080a12437e6c6a101cb99219abf0b345b0a2f90b..0000000000000000000000000000000000000000 --- a/docs/html/tools/studio/studio-features.jd +++ /dev/null @@ -1,340 +0,0 @@ -page.title=Android Studio Features -page.image=images/cards/card-studio-modules_crop_2x.png -page.metaDescription=A quick look at Android Studio features that make your work faster. -page.tags=studio, tools, sdk -meta.tags="studio" - - -@jd:body - -If you're new to Android Studio or exploring recent updates, this -page provides an introduction to some key Android Studio features.
- -For specific Android Studio how-to documentation, see the pages in the Workflow section, such as -Managing Projects from Android Studio -and -Building and Running from Android Studio.
- - - -If your application supports multiple languages, you need to properly manage your -translated string resources. The Translations Editor lets you view and update all your string -resources in one convenient place.
- --Use the Translations Editor to view all your translated resources, modify translations, and add -new locales. You can provide default values for your resources and mark resources as -untranslatable. The Translations Editor also marks resources with missing translations in red, -and provides a link to a page where you can upload resource files and order translation services. -
- -For more details on the Translations Editor, see -Translations Editor.
- -
- Figure 1. Manage locales and strings in the - Translations Editor.
- -Clicking Import Samples from the File menu or Welcome -page provides seamless access to Google code samples on GitHub.
-
Figure 2. Get code samples from GitHub.
- - -
Figure 3. Imported code sample.
- - - -Android Studio supports templates for Google Services and expands the available device -types.
- -For easy cross-platform development, the Project Wizard provides templates for - creating your apps for Android Wear and TV.
-
-
-
Figure 4. Supported form factors.
-During app creation, the Project Wizard also displays an API Level dialog to help you choose - the best minSdkVersion for your project.
- - -Quick cloud integration. Using Google App Engine to connect to the Google cloud - and create a cloud end-point is as easy as selecting File > New Module > App Engine Java - Servlet Module and specifying the module, package, and client names.
-
Figure 5 Google App Engine integration.
- - -Android Studio provides setting dialogs so you can manage the most important Android Studio and
-project settings from the File > Project Structure and
-File > Settings menus. For example, you can use the
-File > Project Structure menu or
-the build.gradle file to update your productFlavor settings.
-Additional settings from the File > Project Structure menus include:
-
buildTypes Use the File > Settings menu to modify the Android Studio or project -behavior, such a UI themes, system settings, and version control.
- - - -Android Studio provides the {@code finger} command, allowing you to simulate, and thus validate, -fingerprint authentication for your app. After you set up your app to accept -fingerprint -authentication, your emulator or device should display the fingerprint authentication screen, -as shown below.
- -
Figure 6 Fingerprint authentication.
- -Open a terminal session, and telnet to the emulator. For example:
-
-{@code telnet localhost 5554}
-
-
-Enter the finger command to simulate finger touch and removal:
finger touch <fingerprint-id> to simulate a finger touching the sensorfinger remove to simulate finger removal Your app should respond as if a user touched, and then removed their finger from, the -fingerprint sensor.
- - -Android Studio supports enabling these developer services in your app:
-Enabling a developer service adds the required dependencies and, when applicable, also modifies
-the related configuration files. To activate the service, you must perform
-service-specific updates, such as loading an ad in the MainActivity class for ad
-display.
To enable an Android developer service, select the File > Project Structure
-menu option and click a service under the Developer Services sub-menu. The service
-configuration page appears. In the service configuration page, click the service check box to
-enable the service and click OK. Android Studio updates your library dependencies
-for the selected service and, for Analytics, updates the AndroidManifest.xml and
-other tracker configuration files. You can enable multiple services within the same app. For more
-detail about starting the services, refer to each service's specific activation instructions.
By default, Android Studio treats all library resources as public: A public library resource is -available to library clients for use outside the library, and appears in code completion suggestions -and other resource references. Android Studio also, however, supports the use of private library -resources. A private library resource can only be used within the source library, and does not -appear in code completion lists and other resource references.
- -You cannot explicitly declare a library resource as private. Instead, if you declare any library -resources as public, Android Studio assumes all the other library resources are private.
- -An app treats all Android library resources as public unless you explicitly declare at least one -resource in the library as public. Declaring one public resource causes your app to treat all other, -undeclared resources in the library as private.
- -Note: Declaring public and private resources requires the -Android Plugin for Gradle version -1.3 or higher.
- - -To declare a resource as public and set other undeclared resources as private, add a
-<public> declaration with the resource name and type in the resource file.
-This example shows the public declaration for the mylib_app_name string resource.
-<resources> - <public name="mylib_app_name" type="string"/> -</resources> -- -
For large numbers of declarations, we recommended that you place the public marker declarations
-in a separate file named public.xml.
To help enforce private resource access, a lint -warning appears when a client of a library references a private resource. Many Android libraries, -such as the -Design Support Library and the -v7 appcompat Library, -declare public resources to display only resources that developers can directly reference. -
- -Note: If your app requires a private resource, copy the -private resource from the library to the location in your app where it is needed.
- -When the build system builds an Android Archive (AAR) file, it extracts the
-<public> resource declarations into a public.txt file, which is
-packaged inside the AAR file next to the R.txt file. The public.txt file
-contains a simple list of the declared public resources, describing their names and types.
For a complete list of the available Android resource types, see -Resource -Types and -More Resource -Types.
- - - -Android Studio supports the
-Material Design themes, widgets, and
-graphics, such as shadow layers and API version rendering (showing the layout across different
-UI versions). Also, the drawable XML tags and attributes, such as <ripple>
-and <animated-selector>, are supported.
Android Studio supports adding a separate test module to your app so you can
-generate a test APK. This test module resides at the same level as your app and
-contains: the tests and instrumentation used to run the test APK on an Android device; an
-Android Manifest.xml file for test APK configuration settings; and, a
-build.gradle file for build settings.
The test module cannot contain a src/androidTest/ folder and does
-not support build variants. If you have different product flavors in your main application APK,
-create a different test module for each build variant.
To create a test APK module: - -
test module consisting of the following directories and files:
- ./test/ ./test/build.gradle ./test/src/main/java/com/android/tests/basic/MainTest.java ./test/src/main/AndroidManifest.xml build.gradle file, add the required properties to the
- android block.
- targetProjectPath ':<app name>' specifies the main application APK
- to test. targetVariant ':<buildType>' specifies the target build type.Here is an example of build.gradle file property settings:
-android {
- compileSdkVersion 19
- buildToolsVersion = ‘21.1.3’
-
- targetProjectPath ':app'
- targetVariant 'debug'
-}
-
- Here is an example of <instrumentation> settings in the manifest file:
-<?xml version="1.0" encoding="utf-8"?> -<manifest xmlns:android="http://schemas.android.com/apk/res/android" - package="com.android.tests.basic.test"> - - <uses-sdk android:minSdkVersion="16" android:targetSdkVersion="16" /> - - <application> - >uses-library android:name="android.test.runner" /> - </application> - - <instrumentation android:name="android.test.InstrumentationTestRunner" - android:targetPackage="com.android.tests.basic" - android:handleProfiling="false" - android:functionalTest="false" - android:label="Tests for com.android.tests.basic"/> -</manifest< -- -
Note: The targetPackage in the instrumentation
-settings specifies the package of the test variant.
build.gradle file for the tested app, include additional artifacts
- that the test APK requires, such as the classes.jar file, by adding the
- {@code publishNonDefault} property to the {@code Android} block, and assigning that property
- a value of {@code true}.
- Here is an example of the build.gradle file that includes additional
- artifacts:
-android {
- compileSdkVersion 19
- buildToolsVersion = ‘21.1.3’
-
- publishNonDefault true
-}
-
-
-
-
-
-In the {@code test} module in this example, the {@code build.gradle} file specifies the -properties for the project path and target build type variant.
- -
Figure 3. Test module for APK testing.
- - -Note: By default, the test module's build variant uses the
-debug build type. You can configure additional build types using the
-testBuildType property in the defaultConfig block in the main
-app's build.gradle file.
- Android Studio provides a number of user interface tools to assist you with creating layouts, - implementing style themes, and building graphic or text resources for your app. -
- -Android provides an integrated testing framework that helps you test all aspects -of your app. The Android SDK and -Testing Support Library include -tools and APIs for setting up and running test apps within an emulator or on the device you are -targeting. You can build and execute tests whether you are working in Android Studio or working -from the command line.
- -To familiarize yourself with mobile app testing in Android, start by reading these resources:
-- Testing is a critical software development activity because it helps you - improve the quality of your apps, ensure better user satisfaction, and - reduce overall development time spent on fixing defects. -
- -The following sections describe tools that help - you test your mobile apps for the Android platform. - -
-This document describes key concepts related to Android app testing. It assumes you have a basic -knowledge of the JUnit testing framework.
- -Android testing is based on JUnit. In general, a JUnit test is a method whose statements test a -part of the application. You organize test methods into classes called -test cases. You can further organize these classes into test suites.
-In JUnit, you build one or more test classes and use a test runner to -execute them. In Android, you use -Android Studio (or the -Android Plugin for Gradle) to build one or more test source files into an -Android test app.
- -From your testing environment, you can run your test in one of the following ways:
-The structure of your test code and the way you build and run the tests in Android Studio depend -on the type of testing you are performing. The following table summarizes the common testing types -for Android:
- -| Type | -Subtype | -Description |
|---|---|---|
| Unit tests | -||
| Local Unit Tests | -Unit tests that run on your local machine only. These tests are compiled to run locally -on the JVM to minimize execution time. Use this approach to run unit tests -that have no dependencies on the Android framework or have dependencies that mock objects can -satisfy. | |
| Instrumented unit tests | -Unit tests that run on an Android device or emulator. These tests have access to -{@link android.app.Instrumentation} information, such as the {@link android.content.Context} of the -app under test. Use this approach to run unit tests that have Android dependencies which mock -objects cannot easily satisfy. | |
| Integration Tests | -||
| Components within your app only | -This type of test verifies that the target app behaves as expected when a user performs -a specific action or enters a specific input in its activities. For example, it allows you to check -that the target app returns the correct UI output in response to user interactions in the app’s -activities. UI testing frameworks like -Espresso allow you to -programmatically simulate user actions and test complex intra-app user interactions. | |
| Cross-app Components | -This type of test verifies the correct behavior of interactions between different user -apps or between user apps and system apps. For example, you might want to test that your app behaves -correctly when the user performs an action in the Android Settings menu. UI testing frameworks -that support cross-app interactions, such as UI Automator, allow you to create tests for such -scenarios. |
Based on the type of test you want to create, you need to configure the test code source -location and the project dependencies in Android Studio as described in -Getting Started with Testing.
- -The following list summarizes the common APIs related to app testing for Android.
- -You should write your unit or integration test class as a JUnit 4 test class. -JUnit is the most popular -and widely-used unit testing framework for Java. The framework offers a convenient way to perform -common setup, teardown, and assertion operations in your test.
- -JUnit 4 allows you to write tests in a cleaner and more -flexible way than its predecessor versions. Unlike the previous approach to Android unit testing -based on JUnit 3, with JUnit 4, you do not need to extend the {@code junit.framework.TestCase} -class. You also do not need to prepend the {@code test} keyword to your test method name, or -use any classes in the {@code junit.framework} or {@code junit.extensions} package.
- -A basic JUnit 4 test class is a Java class that contains one or more test methods. -A test method begins with the {@code @Test} annotation and contains the code to exercise -and verify a single functionality (that is, a logical unit) in the component that you want -to test.
-The following snippet shows an example JUnit 4 integration test that uses the Espresso -APIs to perform a click action on a UI element, then checks to see if an expected string is -displayed.
-
-@RunWith(AndroidJUnit4.class)
-@LargeTest
-public class MainActivityInstrumentationTest {
-
- @Rule
- public ActivityTestRule mActivityRule = new ActivityTestRule<>(
- MainActivity.class);
-
- @Test
- public void sayHello(){
- onView(withText("Say hello!")).perform(click());
-
- onView(withId(R.id.textView)).check(matches(withText("Hello, World!")));
- }
-}
-
-In your JUnit 4 test class, you can call out sections in your test code for -special processing by using the following annotations:
-For more annotations, see the documentation for - -JUnit annotations and the - -Android-specific annotations. -
- You use the JUnit {@link junit.framework.Assert} class to verify the correctness of an object's - state. The assert methods compare values you expect from a test to the actual results and - throw an exception if the comparison fails. - Assertion classes describes these methods in more detail. -
- - -- Android instrumentation is a set of control methods or hooks in the Android system. These - hooks control an Android component independently of its normal lifecycle. They also control how - Android loads applications. -
-- The following diagram summarizes the testing framework: -
-
-
-
-Normally, an Android component runs in a lifecycle that the system determines. For example, an
-{@link android.app.Activity} object's lifecycle starts when an {@link android.content.Intent}
-activates the {@link android.app.Activity}. The system calls the object's onCreate()
-method, on then the onResume() method. When the user starts another application, the
-system calls the onPause() method. If the {@link android.app.Activity} code calls
-the finish() method, the system calls the onDestroy() method. The Android
-framework API does not provide a way for your code to invoke these callback methods directly, but
-you can do so using instrumentation.
-
-The system runs all the components of an application in the same process. You can allow some -components, such as content providers, to run in a separate process, -but you can't force an application to run in the same process as another application that is -already running. -
--Instrumentation can load both a test package and the app under test into the -same process. Since the application components and their tests are in the same process, your -tests can invoke methods in the components, and modify and examine fields in the components. -
--The Android Testing Support Library -provides a set of APIs that allow you to quickly build and run test code for your apps, including -JUnit 4 and functional user interface (UI) tests. The library includes the following -instrumentation-based APIs that are useful when you want to automate your tests:
-Because Android Testing Support Library APIs extend JUnit, you can use assertion methods to -display the results of tests. An assertion method compares an actual value returned by a test to an -expected value, and throws an AssertionException if the comparison test fails. Using assertions -is more convenient than logging, and provides better test performance. -
-To simplify your test development, we recommend that you use the -Hamcrest library, which lets you create more flexible tests using the -Hamcrest matcher APIs.
- -- The SDK provides two tools for functional-level application testing: -
-monkeyrunner command-line
- tool.
- - This document describes how to create and run tests directly from the command line. This - document assumes that you already know how to create a Android application in your programming - environment. -
- -- You can run tests from the command-line, either with Gradle or with an - - Android Debug Bridge (adb) shell. -
-The Android Plugin for Gradle -lets you run unit tests from your Gradle project via the command-line. For more information on -how to build unit tests for your app, see -Building Effective Unit Tests.
- -The table below summarizes how to run your unit tests with Gradle:
-| Unit Test Type | -Command To Run | -Test Result Location | -
|---|---|---|
| Local unit test | -Call the {@code test} task:
--./gradlew test - |
-
-HTML test result files:
-{@code <path_to_your_project>/app/build/reports/tests/} directory.
- XML test result files: -{@code <path_to_your_project>/app/build/test-results/} directory. - |
-
| Instrumented unit test | -Call the {@code connectedAndroidTest} (or {@code cAT}) task:
--./gradlew cAT -- |
-
-HTML test result files:
-{@code <path_to_your_project>/app/build/outputs/reports/androidTests/connected/} directory.
- XML test result files: -{@code <path_to_your_project>/app/build/outputs/androidTest-results/connected/} directory. - |
-
- When you run tests from the command-line with - - Android Debug Bridge (adb), you get more options for choosing the tests - to run than with any other method. You can select individual test methods, filter tests - according to their annotation, or specify testing options. Since the test run is controlled - entirely from a command-line, you can customize your testing with shell scripts in various ways. -
-
- To run a test from the command-line, you run adb shell to start a command-line
- shell on your device or emulator, and then in the shell run the am instrument
- command. You control am and your tests with command-line flags.
-
- As a shortcut, you can start an adb shell, call am instrument, and
- specify command-line flags all on one input line. The shell opens on the device or emulator,
- runs your tests, produces output, and then returns to the command-line on your computer.
-
- To run a test with am instrument:
-
.apk files) to your current Android device or emulator-$ adb shell am instrument -w <test_package_name>/<runner_class> --
- where <test_package_name> is the Android package name of your test
- application, and <runner_class> is the name of the Android test
- runner class you are using. The Android package name is the value of the
- package attribute of the manifest element in the manifest file
- (AndroidManifest.xml) of your test package. The Android test runner
- class is usually
-
-{@code AndroidJUnitRunner}.
-
- Your test results appear in STDOUT.
-
- This operation starts an adb shell, then runs am instrument
- with the specified parameters. This particular form of the command will run all of the tests
- in your test package. You can control this behavior with flags that you pass to
- am instrument. These flags are described in the next section.
-
- The general syntax of the am instrument command is:
-
-am instrument [flags] <test_package>/<runner_class> --
- The main input parameters to am instrument are described in the following table:
-
| - Parameter - | -- Value - | -- Description - | -
|---|---|---|
- <test_package>
- |
- - The Android package name of the test package. - | -
- The value of the package attribute of the manifest
- element in the test package's manifest file.
- |
-
- <runner_class>
- |
- - The class name of the instrumented test runner you are using. - | -- This is usually - -{@code AndroidJUnitRunner}. - | -
- The flags for am instrument are described in the following table:
-
| - Flag - | -- Value - | -- Description - | -
|---|---|---|
- -w
- |
- - (none) - | -
- Forces am instrument to wait until the instrumentation terminates
- before terminating itself. The net effect is to keep the shell open until the tests
- have finished. This flag is not required, but if you do not use it, you will not
- see the results of your tests.
- |
-
- -r
- |
- - (none) - | -
- Outputs results in raw format. Use this flag when you want to collect
- performance measurements, so that they are not formatted as test results. This flag is
- designed for use with the flag -e perf true (documented in the section
- Instrument options).
- |
-
- -e
- |
- - <test_options> - | -
- Provides testing options as key-value pairs. The
- am instrument tool passes these to the specified instrumentation class
- via its onCreate() method. You can specify multiple occurrences of
- -e <test_options>. The keys and values are described in the
- section am instrument options. You can only use these
- key-value pairs with
-
-{@code AndroidJUnitRunner} or with {@link android.test.InstrumentationTestRunner} and its
-subclasses. Using them with any other class has no effect.
- |
-
- The am instrument tool passes testing options to
-
-{@code AndroidJUnitRunner} or {@link android.test.InstrumentationTestRunner} in the form of
-key-value pairs, using the -e flag, with this syntax:
-
--e <key> <value> --
- Some keys accept multiple values. You specify multiple values in a comma-separated list.
- For example, this invocation of
-
-{@code AndroidJUnitRunner} provides multiple values for the package key:
-
-$ adb shell am instrument -w -e package com.android.test.package1,com.android.test.package2 \ -> com.android.test/android.support.test.runner.AndroidJUnitRunner --
The following table lists the key-value pairs you can use with your test runner.
-| Key | -Value | -Description | -
|---|---|---|
- package
- |
- - <Java_package_name> - | -- The fully-qualified Java package name for one of the packages in the test - application. Any test case class that uses this package name is executed. Notice that - this is not an Android package name; a test package has a single - Android package name but may have several Java packages within it. - | -
class |
- <class_name> | -- The fully-qualified Java class name for one of the test case classes. Only this test - case class is executed. - | -
| <class_name>#method name | -- A fully-qualified test case class name, and one of its methods. Only this method is - executed. Note the hash mark (#) between the class name and the method name. - | -|
func |
- true |
- - Runs all test classes that extend {@link android.test.InstrumentationTestCase}. - | -
unit |
- true |
- - Runs all test classes that do not extend either - {@link android.test.InstrumentationTestCase} or - {@link android.test.PerformanceTestCase}. - | -
size |
-
- [small | medium | large]
- |
-
- Runs a test method annotated by size. The annotations are @SmallTest,
- @MediumTest, and @LargeTest.
- |
-
perf |
- true |
-
- Runs all test classes that implement {@link android.test.PerformanceTestCase}.
- When you use this option, also specify the -r flag for
- am instrument, so that the output is kept in raw format and not
- re-formatted as test results.
- |
-
debug |
- true |
- - Runs tests in debug mode. - | -
log |
- true |
-
- Loads and logs all specified tests, but does not run them. The test
- information appears in STDOUT. Use this to verify combinations of other
- filters and test specifications.
- |
-
emma |
- true |
-
- Runs an EMMA code coverage analysis and writes the output to
- /data/<app_package>/coverage.ec on the device. To override the
- file location, use the coverageFile key that is described in the
- following entry.
-
- Note: This option requires an EMMA-instrumented build of the test
- application, which you can generate with the |
-
coverageFile |
- <filename> |
-
- Overrides the default location of the EMMA coverage file on the device. Specify this
- value as a path and filename in UNIX format. The default filename is described in the
- entry for the emma key.
- |
-
-e Flag Usage Notes
-am instrument invokes
- {@link android.test.InstrumentationTestRunner#onCreate(Bundle)}
- with a {@link android.os.Bundle} containing the key-value pairs.
- package key takes precedence over the class key. If you
- specifiy a package, and then separately specify a class within that package, Android
- will run all the tests in the package and ignore the class key.
- func key and unit key are mutually exclusive.
-
-The following sections provide examples of using am instrument to run tests.
-They are based on the following structure:
com.android.demo.app.tests
- - To run all of the test classes in the test package, enter: -
--$ adb shell am instrument -w com.android.demo.app.tests/android.support.test.runner.AndroidJUnitRunner --
- To run all of the tests in the class UnitTests, enter:
-
-$ adb shell am instrument -w \ -> -e class com.android.demo.app.tests.Foo \ -> com.android.demo.app.tests/android.support.test.runner.AndroidJUnitRunner --
- am instrument gets the value of the -e flag, detects the
- class keyword, and runs all the methods in the UnitTests class.
-
- To run all of the tests in Foo1, and the bar3 method in
- Foo2, enter:
-
-$ adb shell am instrument -w \ -> -e class com.android.demo.app.tests.Foo1,com.android.demo.app.tests.Foo2#bar3 \ -> com.android.demo.app.tests/android.support.test.runner.AndroidJUnitRunner -diff --git a/docs/html/tools/tools_toc.cs b/docs/html/tools/tools_toc.cs deleted file mode 100644 index 73d4ff3738c9e4ca99378a6dbd344112ecece9f0..0000000000000000000000000000000000000000 --- a/docs/html/tools/tools_toc.cs +++ /dev/null @@ -1,473 +0,0 @@ - - - - - -
Developing applications for Android devices is facilitated by a group of tools that are - provided with the SDK. You can access these tools through Android Studio or from the command line. Developing with Android Studio is the preferred method because - it can directly invoke the tools that you need while developing applications.
- -However, you may choose to develop with another IDE or a simple text editor and invoke the - tools on the command line or with scripts. This is a less streamlined way to develop because you - will sometimes have to call command line tools manually, but you will have access to the same - number of features that you would have in Android Studio.
- -
- - Figure 1. The development process for Android applications. -
-The basic steps for developing applications (with or without Android Studio) are shown in figure 1. The -development steps encompass four development phases, which include:
- -During this phase you install and set up your development environment. You also create - Android Virtual Devices (AVDs) and connect hardware devices on which you can install your - applications.
-See Managing Virtual Devices - and Using Hardware Devices for more - information. -
During this phase you set up and develop your Android project, which contains all of the - source code and resource files for your application. For more informations, see - Create an Android project.
-During this phase you build your project into a debuggable .apk package that you
- can install and run on the emulator or an Android-powered device. Android Studio uses
- a build system based on Gradle
- that provides flexibility, customized build variants, dependency resolution, and much more.
- If you're using another IDE, you can build your project using Gradle and install it on a device
- using adb. For more information, see
- Build and run your application.
Next, you debug your application using a JDWP-compliant debugger along with the debugging - and logging tools that are provided with the Android SDK. Android Studio already comes packaged with - a compatible debugger. For more information see, - Debug your application with the - SDK debugging and logging tools.
-Last, you test your application using various Android SDK testing tools. For more - information, see Test your application - with the Testing and Instrumentation framework.
-During this phase you configure and build your application for release and distribute your - application to users. For more information, see - Publishing Overview.
-When developing in IDEs or editors other than Android Studio, be familiar with - all of the tools below, because you will have to run them from the command line.
- -In addition to the above tools that are included with the SDK, you need the following open - source and third-party tools:
- -If you are using Android Studio, tools such as adb and android
- are automatically called by Android Studio, so you don't have to manually invoke these tools.
- You need to be familiar with adb, however, because certain functions are not
-accessible from
- Android Studio, such as the adb shell commands. You might also need to call Keytool and
-Jarsigner to
- sign your applications, but you can set up Android Studio to do this automatically as well.
For more information on the tools provided with the Android SDK, see the - Tools section of the documentation.
- -- The tools described in this section are not developed by the Android SDK team. The Android Dev Guide - does not provide documentation for these tools. Please refer to the linked documents in each - section for documentation. -
-- IntelliJ IDEA is a powerful Java IDE from JetBrains that provides - full-cycle Android development support in both the free Community - Edition and the Ultimate edition. -
-- The IDE ensures compatibility with the latest Android SDK and offers a - smart code editor with completion, quick navigation between code and - resources, a graphical debugger, unit testing support using Android - Testing Framework, and the ability to run applications in either the - emulator or a USB-connected device. -
-- Links: -
-To develop apps for Android, you use a set of tools that are included in Android Studio. -In addition to using the tools from Android Studio, -you can also access most of the SDK tools from the command line. Developing with Android Studio is the -preferred method because it can directly invoke the tools that you need while developing applications.
- -However, you may choose to develop with another IDE or a simple text editor and invoke the -tools on the command line or with scripts. This is a less streamlined way to develop because you -will sometimes have to call command line tools manually, but you will have access to the same -number of features that you would have in Android Studio.
- -
- - Figure 1. The development process for Android applications. -
-The basic steps for developing applications (with or without Android Studio) are shown in -figure 1. The development steps encompass four development phases, which include:
- -During this phase you install and set up your development environment. You also create - Android Virtual Devices (AVDs) and connect hardware devices on which you can install your - applications.
-See Managing Virtual Devices - and Using Hardware Devices for more - information. -
During this phase you set up and develop your Android Studio project and application modules, - which contain all of the source code and resource files for your application. For more - information, see - Create an Android project.
-During this phase you build your project into a debuggable .apk package(s)
- that you can install and run on the emulator or an Android-powered device. Android Studio uses
- a build system based on Gradle
- that provides flexibility, customized build variants, dependency resolution, and much more.
- If you're using another IDE, you can build your project using Gradle and install it on a device
- using adb. For more information, see
- Build and run your application.
Next, with Android Studio you debug your application using the - Android Device Monitor and device log messages - (logcat) along with the IntelliJ IDEA intelligent - coding features. You can also use a JDWP-compliant debugger along with the debugging and logging - tools that are provided with the Android SDK. For more information see - Debug your application with the SDK debugging and logging tools.
-Last, you test your application using various Android SDK testing tools. For more - information, see Test your application - with the Testing and Instrumentation framework.
-During this phase you configure and build your application for release and distribute your - application to users. For more information, see - Publishing - Overview.
-When developing in IDEs or editors other than Android Studio, be familiar with - all of the tools below, because you will have to run them from the command line or script.
- -In addition to the above tools that are included with the SDK, you need the following open - source and third-party tools:
- -If you are using Android Studio, tools such as adb and android
- are automatically called by Android Studio so you don't have to manually invoke these tools.
- You need to be familiar with adb, however, because certain functions are not
- accessible from Android Studio, such as the adb shell commands. You might also
- need to call Keytool and Jarsigner to sign your applications, but you can set up Android Studio
- to do this automatically as well.
For more information on the tools provided with the Android SDK, see the - Tools section of the documentation.
- - -