diff options
Diffstat (limited to 'docs')
29 files changed, 2631 insertions, 1215 deletions
diff --git a/docs/html/about/versions/android-4.0.3.jd b/docs/html/about/versions/android-4.0.3.jd index 5fa8547..4c2ccb9 100644 --- a/docs/html/about/versions/android-4.0.3.jd +++ b/docs/html/about/versions/android-4.0.3.jd @@ -78,19 +78,19 @@ can now sync that data with each of the user’s contacts, providing items in a stream along with photos for each.</p> <p>The database table that contains an individual contact’s social stream is -defined by {@link android.provider.ContactsContract.StreamItems}, the Uri for +defined by android.provider.ContactsContract.StreamItems, the Uri for which is nested within the {@link android.provider.ContactsContract.RawContacts} directory to which the stream items belong. Each social stream table includes several columns for metadata about each stream item, such as an icon representing the source (an avatar), a label for the item, the primary text content, comments about the item (such as responses from other people), and more. Photos associated with a stream are stored in another table, defined by -{@link android.provider.ContactsContract.StreamItemPhotos}, which is available -as a sub-directory of the {@link android.provider.ContactsContract.StreamItems} +android.provider.ContactsContract.StreamItemPhotos, which is available +as a sub-directory of the android.provider.ContactsContract.StreamItems Uri.</p> -<p>See {@link android.provider.ContactsContract.StreamItems} and -{@link android.provider.ContactsContract.StreamItemPhotos} for more information.</p> +<p>See android.provider.ContactsContract.StreamItems and +android.provider.ContactsContract.StreamItemPhotos for more information.</p> <p>To read or write social stream items for a contact, an application must request permission from the user by declaring <code><uses-permission @@ -272,8 +272,8 @@ let you check and manage video stabilization for a {@link android.hardware.Camer <p>The following are new permissions:</p> <ul> -<li>{@link android.Manifest.permission#READ_SOCIAL_STREAM} and -{@link android.Manifest.permission#WRITE_SOCIAL_STREAM}: Allow a sync +<li>android.Manifest.permission#READ_SOCIAL_STREAM and +android.Manifest.permission#WRITE_SOCIAL_STREAM: Allow a sync adapter to read and write social stream data to a contact in the shared Contacts Provider.</li> </ul> diff --git a/docs/html/about/versions/android-4.0.jd b/docs/html/about/versions/android-4.0.jd index 6c4ccb4..cc1d1c7 100644 --- a/docs/html/about/versions/android-4.0.jd +++ b/docs/html/about/versions/android-4.0.jd @@ -108,9 +108,9 @@ android.provider.ContactsContract.RawContacts} Uri; instead, you must add a prof the table at {@link android.provider.ContactsContract.Profile#CONTENT_RAW_CONTACTS_URI}. Raw contacts in this table are then aggregated into the single user-visible profile labeled "Me".</p> -<p>Adding a new raw contact for the profile requires the {@link -android.Manifest.permission#WRITE_PROFILE} permission. Likewise, in order to read from the profile -table, you must request the {@link android.Manifest.permission#READ_PROFILE} permission. However, +<p>Adding a new raw contact for the profile requires the +android.Manifest.permission#WRITE_PROFILE permission. Likewise, in order to read from the profile +table, you must request the android.Manifest.permission#READ_PROFILE permission. However, most apps should not need to read the user profile, even when contributing data to the profile. Reading the user profile is a sensitive permission and you should expect users to be skeptical of apps that request it.</p> @@ -1638,9 +1638,9 @@ messages to the device.</li> android.service.textservice.SpellCheckerService} must require this permission for itself.</li> <li>{@link android.Manifest.permission#BIND_VPN_SERVICE}: A service that implements {@link android.net.VpnService} must require this permission for itself.</li> -<li>{@link android.Manifest.permission#READ_PROFILE}: Provides read access to the {@link +<li>android.Manifest.permission#READ_PROFILE: Provides read access to the {@link android.provider.ContactsContract.Profile} provider.</li> -<li>{@link android.Manifest.permission#WRITE_PROFILE}: Provides write access to the {@link +<li>android.Manifest.permission#WRITE_PROFILE: Provides write access to the {@link android.provider.ContactsContract.Profile} provider.</li> </ul> diff --git a/docs/html/about/versions/android-4.1.jd b/docs/html/about/versions/android-4.1.jd index 76b90ac..f8770fa 100644 --- a/docs/html/about/versions/android-4.1.jd +++ b/docs/html/about/versions/android-4.1.jd @@ -871,7 +871,7 @@ read access using this permission. If your application already requests write a automatically get read access as well. There is a new developer option to turn on read access restriction, for developers to test their applications against how Android will behave in the future.</dd> - <dt>{@link android.Manifest.permission#READ_USER_DICTIONARY}</dt> + <dt>android.Manifest.permission.READ_USER_DICTIONARY</dt> <dd>Allows an application to read the user dictionary. This should only be required by an IME, or a dictionary editor like the Settings app.</dd> <dt>{@link android.Manifest.permission#READ_CALL_LOG}</dt> @@ -879,7 +879,7 @@ IME, or a dictionary editor like the Settings app.</dd> incoming and outgoing calls.</dd> <dt>{@link android.Manifest.permission#WRITE_CALL_LOG}</dt> <dd>Allows an application to modify the system's call log stored on your phone</dd> - <dt>{@link android.Manifest.permission#WRITE_USER_DICTIONARY}</dt> + <dt>android.Manifest.permission.WRITE_USER_DICTIONARY</dt> <dd>Allows an application to write to the user's word dictionary.</dd> </dl> diff --git a/docs/html/about/versions/android-4.3.jd b/docs/html/about/versions/android-4.3.jd index e18c285..2496854 100644 --- a/docs/html/about/versions/android-4.3.jd +++ b/docs/html/about/versions/android-4.3.jd @@ -1029,7 +1029,7 @@ APIs allow you to inspect the screen content and inject arbitrary keyboard and t android.app.Instrumentation#getUiAutomation Instrumentation.getUiAutomation()}. In order for this to work, you must supply the {@code -w} option with the {@code instrument} command when running your {@link android.test.InstrumentationTestCase} from <a -href="{@docRoot}tools/help/adb.html#am">{@code adb shell}</a>.</p> +href="{@docRoot}tools/help/shell.html#am">{@code adb shell}</a>.</p> <p>With the {@link android.app.UiAutomation} instance, you can execute arbitrary events to test your app by calling {@link android.app.UiAutomation#executeAndWaitForEvent diff --git a/docs/html/guide/components/intents-common.jd b/docs/html/guide/components/intents-common.jd index 167ebde..8aa5fa9 100644 --- a/docs/html/guide/components/intents-common.jd +++ b/docs/html/guide/components/intents-common.jd @@ -2236,7 +2236,7 @@ adb shell am start -a android.intent.action.DIAL \ <p>For more information, see -<a href="{@docRoot}tools/help/adb.html#am">Using activity manager (am)</a>.</p> +<a href="{@docRoot}tools/help/shell.html#am">ADB Shell Commands</a>.</p> diff --git a/docs/html/guide/topics/providers/contacts-provider.jd b/docs/html/guide/topics/providers/contacts-provider.jd index e3b998a..2b14558 100644 --- a/docs/html/guide/topics/providers/contacts-provider.jd +++ b/docs/html/guide/topics/providers/contacts-provider.jd @@ -57,7 +57,7 @@ page.title=Contacts Provider <li>{@link android.provider.ContactsContract.Contacts}</li> <li>{@link android.provider.ContactsContract.RawContacts}</li> <li>{@link android.provider.ContactsContract.Data}</li> - <li>{@link android.provider.ContactsContract.StreamItems}</li> + <li>android.provider.ContactsContract.StreamItems</li> </ol> <h2>Related Samples</h2> <ol> @@ -606,13 +606,13 @@ page.title=Contacts Provider Access to the user profile requires special permissions. In addition to the {@link android.Manifest.permission#READ_CONTACTS} and {@link android.Manifest.permission#WRITE_CONTACTS} permissions needed to read and write, access - to the user profile requires the {@link android.Manifest.permission#READ_PROFILE} and - {@link android.Manifest.permission#WRITE_PROFILE} permissions for read and write access, + to the user profile requires the android.Manifest.permission#READ_PROFILE and + android.Manifest.permission#WRITE_PROFILE permissions for read and write access, respectively. </p> <p> Remember that you should consider a user's profile to be sensitive. The permission - {@link android.Manifest.permission#READ_PROFILE} allows you to access the device user's + android.Manifest.permission#READ_PROFILE allows you to access the device user's personally-identifying data. Make sure to tell the user why you need user profile access permissions in the description of your application. </p> @@ -1826,8 +1826,8 @@ child elements that provide specific data to the </dl> <h2 id="SocialStream">Social Stream Data</h2> <p> - The {@link android.provider.ContactsContract.StreamItems} and - {@link android.provider.ContactsContract.StreamItemPhotos} tables + The android.provider.ContactsContract.StreamItems and + android.provider.ContactsContract.StreamItemPhotos tables manage incoming data from social networks. You can write a sync adapter that adds stream data from your own network to these tables, or you can read stream data from these tables and display it in your own application, or both. With these features, your social networking @@ -1836,7 +1836,7 @@ child elements that provide specific data to the <h3 id="StreamText">Social stream text</h3> <p> Stream items are always associated with a raw contact. The - {@link android.provider.ContactsContract.StreamItemsColumns#RAW_CONTACT_ID} links to the + android.provider.ContactsContract.StreamItemsColumns#RAW_CONTACT_ID links to the <code>_ID</code> value for the raw contact. The account type and account name of the raw contact are also stored in the stream item row. </p> @@ -1845,14 +1845,14 @@ child elements that provide specific data to the </p> <dl> <dt> - {@link android.provider.ContactsContract.StreamItemsColumns#ACCOUNT_TYPE} + android.provider.ContactsContract.StreamItemsColumns#ACCOUNT_TYPE </dt> <dd> <strong>Required.</strong> The user's account type for the raw contact associated with this stream item. Remember to set this value when you insert a stream item. </dd> <dt> - {@link android.provider.ContactsContract.StreamItemsColumns#ACCOUNT_NAME} + android.provider.ContactsContract.StreamItemsColumns#ACCOUNT_NAME </dt> <dd> <strong>Required.</strong> The user's account name for the raw contact associated with this @@ -1866,30 +1866,30 @@ child elements that provide specific data to the insert a stream item: <ul> <li> - {@link android.provider.ContactsContract.StreamItemsColumns#CONTACT_ID}: The - {@link android.provider.BaseColumns#_ID} value of the contact that this stream + android.provider.ContactsContract.StreamItemsColumns#CONTACT_ID: The + android.provider.BaseColumns#_ID value of the contact that this stream item is associated with. </li> <li> - {@link android.provider.ContactsContract.StreamItemsColumns#CONTACT_LOOKUP_KEY}: The - {@link android.provider.ContactsContract.ContactsColumns#LOOKUP_KEY} value of the + android.provider.ContactsContract.StreamItemsColumns#CONTACT_LOOKUP_KEY: The + android.provider.ContactsContract.ContactsColumns#LOOKUP_KEY value of the contact this stream item is associated with. </li> <li> - {@link android.provider.ContactsContract.StreamItemsColumns#RAW_CONTACT_ID}: The - {@link android.provider.BaseColumns#_ID} value of the raw contact that this stream + android.provider.ContactsContract.StreamItemsColumns#RAW_CONTACT_ID: The + android.provider.BaseColumns#_ID value of the raw contact that this stream item is associated with. </li> </ul> </dd> <dt> - {@link android.provider.ContactsContract.StreamItemsColumns#COMMENTS} + android.provider.ContactsContract.StreamItemsColumns#COMMENTS </dt> <dd> Optional. Stores summary information that you can display at the beginning of a stream item. </dd> <dt> - {@link android.provider.ContactsContract.StreamItemsColumns#TEXT} + android.provider.ContactsContract.StreamItemsColumns#TEXT </dt> <dd> The text of the stream item, either the content that was posted by the source of the item, @@ -1899,7 +1899,7 @@ child elements that provide specific data to the ellipsize long content, but it will try to avoid breaking tags. </dd> <dt> - {@link android.provider.ContactsContract.StreamItemsColumns#TIMESTAMP} + android.provider.ContactsContract.StreamItemsColumns#TIMESTAMP </dt> <dd> A text string containing the time the stream item was inserted or updated, in the form @@ -1910,42 +1910,42 @@ child elements that provide specific data to the </dl> <p> To display identifying information for your stream items, use the - {@link android.provider.ContactsContract.StreamItemsColumns#RES_ICON}, - {@link android.provider.ContactsContract.StreamItemsColumns#RES_LABEL}, and - {@link android.provider.ContactsContract.StreamItemsColumns#RES_PACKAGE} to link to resources + android.provider.ContactsContract.StreamItemsColumns#RES_ICON, + android.provider.ContactsContract.StreamItemsColumns#RES_LABEL, and + android.provider.ContactsContract.StreamItemsColumns#RES_PACKAGE to link to resources in your application. </p> <p> - The {@link android.provider.ContactsContract.StreamItems} table also contains the columns - {@link android.provider.ContactsContract.StreamItemsColumns#SYNC1} through - {@link android.provider.ContactsContract.StreamItemsColumns#SYNC4} for the exclusive use of + The android.provider.ContactsContract.StreamItems table also contains the columns + android.provider.ContactsContract.StreamItemsColumns#SYNC1 through + android.provider.ContactsContract.StreamItemsColumns#SYNC4 for the exclusive use of sync adapters. </p> <h3 id="StreamPhotos">Social stream photos</h3> <p> - The {@link android.provider.ContactsContract.StreamItemPhotos} table stores photos associated + The android.provider.ContactsContract.StreamItemPhotos table stores photos associated with a stream item. The table's - {@link android.provider.ContactsContract.StreamItemPhotosColumns#STREAM_ITEM_ID} column + android.provider.ContactsContract.StreamItemPhotosColumns#STREAM_ITEM_ID column links to values in the {@link android.provider.BaseColumns#_ID} column of - {@link android.provider.ContactsContract.StreamItems} table. Photo references are stored in the + android.provider.ContactsContract.StreamItems table. Photo references are stored in the table in these columns: </p> <dl> <dt> - {@link android.provider.ContactsContract.StreamItemPhotos#PHOTO} column (a BLOB). + android.provider.ContactsContract.StreamItemPhotos#PHOTO column (a BLOB). </dt> <dd> A binary representation of the photo, resized by the provider for storage and display. This column is available for backwards compatibility with previous versions of the Contacts Provider that used it for storing photos. However, in the current version you should not use this column to store photos. Instead, use - either {@link android.provider.ContactsContract.StreamItemPhotosColumns#PHOTO_FILE_ID} or - {@link android.provider.ContactsContract.StreamItemPhotosColumns#PHOTO_URI} (both of + either android.provider.ContactsContract.StreamItemPhotosColumns#PHOTO_FILE_ID or + android.provider.ContactsContract.StreamItemPhotosColumns#PHOTO_URI (both of which are described in the following points) to store photos in a file. This column now contains a thumbnail of the photo, which is available for reading. </dd> <dt> - {@link android.provider.ContactsContract.StreamItemPhotosColumns#PHOTO_FILE_ID} + android.provider.ContactsContract.StreamItemPhotosColumns#PHOTO_FILE_ID </dt> <dd> A numeric identifier of a photo for a raw contact. Append this value to the constant @@ -1955,7 +1955,7 @@ child elements that provide specific data to the openAssetFileDescriptor()} to get a handle to the photo file. </dd> <dt> - {@link android.provider.ContactsContract.StreamItemPhotosColumns#PHOTO_URI} + android.provider.ContactsContract.StreamItemPhotosColumns#PHOTO_URI </dt> <dd> A content URI pointing directly to the photo file for the photo represented by this row. @@ -1970,27 +1970,27 @@ child elements that provide specific data to the <ul> <li> These tables require additional access permissions. To read from them, your application - must have the permission {@link android.Manifest.permission#READ_SOCIAL_STREAM}. To + must have the permission android.Manifest.permission#READ_SOCIAL_STREAM. To modify them, your application must have the permission - {@link android.Manifest.permission#WRITE_SOCIAL_STREAM}. + android.Manifest.permission#WRITE_SOCIAL_STREAM. </li> <li> - For the {@link android.provider.ContactsContract.StreamItems} table, the number of rows + For the android.provider.ContactsContract.StreamItems table, the number of rows stored for each raw contact is limited. Once this limit is reached, the Contacts Provider makes space for new stream item rows by automatically deleting the rows having the oldest - {@link android.provider.ContactsContract.StreamItemsColumns#TIMESTAMP}. To get the + android.provider.ContactsContract.StreamItemsColumns#TIMESTAMP. To get the limit, issue a query to the content URI - {@link android.provider.ContactsContract.StreamItems#CONTENT_LIMIT_URI}. You can leave + android.provider.ContactsContract.StreamItems#CONTENT_LIMIT_URI. You can leave all the arguments other than the content URI set to <code>null</code>. The query returns a Cursor containing a single row, with the single column - {@link android.provider.ContactsContract.StreamItems#MAX_ITEMS}. + android.provider.ContactsContract.StreamItems#MAX_ITEMS. </li> </ul> <p> - The class {@link android.provider.ContactsContract.StreamItems.StreamItemPhotos} defines a - sub-table of {@link android.provider.ContactsContract.StreamItemPhotos} containing the photo + The class android.provider.ContactsContract.StreamItems.StreamItemPhotos defines a + sub-table of android.provider.ContactsContract.StreamItemPhotos containing the photo rows for a single stream item. </p> <h3 id="SocialStreamInteraction">Social stream interactions</h3> @@ -2003,8 +2003,8 @@ child elements that provide specific data to the <li> By syncing your social networking service to the Contacts Provider with a sync adapter, you can retrieve recent activity for a user's contacts and store it in - the {@link android.provider.ContactsContract.StreamItems} and - {@link android.provider.ContactsContract.StreamItemPhotos} tables for later use. + the android.provider.ContactsContract.StreamItems and + android.provider.ContactsContract.StreamItemPhotos tables for later use. </li> <li> Besides regular synchronization, you can trigger your sync adapter to retrieve @@ -2356,6 +2356,6 @@ child elements that provide specific data to the </p> <p> Social stream data for a person may also include photos. These are stored in the - {@link android.provider.ContactsContract.StreamItemPhotos} table, which is described in more + android.provider.ContactsContract.StreamItemPhotos table, which is described in more detail in the section <a href="#StreamPhotos">Social stream photos</a>. </p> diff --git a/docs/html/guide/topics/security/permissions.jd b/docs/html/guide/topics/security/permissions.jd index 6f919da..cfab3c9 100644 --- a/docs/html/guide/topics/security/permissions.jd +++ b/docs/html/guide/topics/security/permissions.jd @@ -52,9 +52,7 @@ must explicitly share resources and data. They do this by declaring the <em>permissions</em> they need for additional capabilities not provided by the basic sandbox. Applications statically declare the permissions they require, and the Android system prompts the user for consent at the time the -application is installed. Android has no mechanism for granting permissions -dynamically (at run-time) because it complicates the user experience to the -detriment of security.</p> +application is installed.</p> <p>The application sandbox does not depend on the technology used to build an application. In particular the Dalvik VM is not a security boundary, and diff --git a/docs/html/images/tools/eclipse-notepad-pre-import--structure.png b/docs/html/images/tools/eclipse-notepad-pre-import--structure.png Binary files differnew file mode 100644 index 0000000..b9c3814 --- /dev/null +++ b/docs/html/images/tools/eclipse-notepad-pre-import--structure.png diff --git a/docs/html/images/tools/studio-import-destination-dir.png b/docs/html/images/tools/studio-import-destination-dir.png Binary files differnew file mode 100644 index 0000000..d1c6c70 --- /dev/null +++ b/docs/html/images/tools/studio-import-destination-dir.png diff --git a/docs/html/images/tools/studio-import-options.png b/docs/html/images/tools/studio-import-options.png Binary files differnew file mode 100644 index 0000000..f14eca0 --- /dev/null +++ b/docs/html/images/tools/studio-import-options.png diff --git a/docs/html/images/tools/studio-import-project-structure-android.png b/docs/html/images/tools/studio-import-project-structure-android.png Binary files differnew file mode 100644 index 0000000..4cd7186 --- /dev/null +++ b/docs/html/images/tools/studio-import-project-structure-android.png diff --git a/docs/html/images/tools/studio-import-project-structure-project.png b/docs/html/images/tools/studio-import-project-structure-project.png Binary files differnew file mode 100644 index 0000000..c7ffda8 --- /dev/null +++ b/docs/html/images/tools/studio-import-project-structure-project.png diff --git a/docs/html/images/tools/studio-import-summary.png b/docs/html/images/tools/studio-import-summary.png Binary files differnew file mode 100644 index 0000000..a85e339 --- /dev/null +++ b/docs/html/images/tools/studio-import-summary.png diff --git a/docs/html/images/tools/studio-select-project-forimport.png b/docs/html/images/tools/studio-select-project-forimport.png Binary files differnew file mode 100644 index 0000000..c6a3599 --- /dev/null +++ b/docs/html/images/tools/studio-select-project-forimport.png diff --git a/docs/html/jd_collections.js b/docs/html/jd_collections.js index e677f64..c5b0b85 100644 --- a/docs/html/jd_collections.js +++ b/docs/html/jd_collections.js @@ -1611,7 +1611,8 @@ var RESOURCE_COLLECTIONS = { "title": "", "resources": [ "training/enterprise/work-policy-ctrl.html", - "samples/BasicManagedProfile/index.html" + "samples/BasicManagedProfile/index.html", + "https://www.youtube.com/watch?v=j3QC6hcpy90" ] }, "tools/performance/rendering": { diff --git a/docs/html/sdk/installing/installing-adt.jd b/docs/html/sdk/installing/installing-adt.jd index 5559d1a..b89c068 100644 --- a/docs/html/sdk/installing/installing-adt.jd +++ b/docs/html/sdk/installing/installing-adt.jd @@ -7,6 +7,14 @@ adt.zip.checksum=f64b7e50c84799f41c642218c35f1bbe @jd:body +<p class="caution"> + <strong>Important:</strong> Support for the Android Developer Tools (ADT) in Eclipse is ending, + per our <a href= + "http://android-developers.blogspot.com/2015/06/an-update-on-eclipse-android-developer.html" + class="external-link">announcement</a>. You should migrate your app development projects to + Android Studio as soon as possible. For more information on transitioning to Android Studio, see + <a href="{@docRoot}sdk/installing/migrate.html">Migrating to Android Studio</a>. +</p> <p>Android offers a custom plugin for the Eclipse IDE, called Android Development Tools (ADT). This plugin provides a powerful, integrated @@ -15,15 +23,6 @@ of Eclipse to let you quickly set up new Android projects, build an app UI, debug your app, and export signed (or unsigned) app packages (APKs) for distribution. </p> -<p class="note"><strong>Note:</strong> -If you have been using Eclipse with ADT, be aware that <a -href="{@docRoot}tools/studio/index.html">Android Studio</a> 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 <a href="/sdk/installing/migrate.html">Migrating to Android -Studio</a>.</p> - - <p>You should install the ADT plugin only if you already have an Eclipse installation that you want to continue using. Your existing Eclipse installation must meet these requirements:</p> diff --git a/docs/html/sdk/installing/migrate.jd b/docs/html/sdk/installing/migrate.jd index 345e89a..d9829395 100644 --- a/docs/html/sdk/installing/migrate.jd +++ b/docs/html/sdk/installing/migrate.jd @@ -4,53 +4,264 @@ page.title=Migrating to Android Studio <div id="qv-wrapper"> <div id="qv"> + + +<h2>In this document</h2> +<ol> + <li><a href="#overview">Migration Overview</a></li> + <li><a href="#prerequisites">Migration Prerequisites</a></li> + <li><a href="#migrate">Importing Projects to Android Studio</a></li> + <li><a href="#post-migration">Validating imported projects</a></li> +</ol> + + <h2>See also</h2> <ul> + <li><a href="{@docRoot}tools/studio/eclipse-transition-guide.html"> + Transition Guide for Eclipse ADT</a></li> <li><a href="http://confluence.jetbrains.com/display/IntelliJIDEA/FAQ+on+Migrating+to+IntelliJ+IDEA" - class="external-link">IntelliJ FAQ on migrating to IntelliJ IDEA</a></li> - <li><a href="http://confluence.jetbrains.com/display/IntelliJIDEA/Working+in+Eclipse+Compatibility+Mode" class="external-link" - >Eclipse Compatibility Mode</a></li> - <li><a href="http://confluence.jetbrains.com/display/IntelliJIDEA/FAQ+on+Migrating+to+IntelliJ+IDEA" class="external-link" - >FAQ on Migrating</a></li> + class="external-link">IntelliJ FAQ on migrating to IntelliJ IDEA</a></li> + <li><a href="http://confluence.jetbrains.com/display/IntelliJIDEA/IntelliJ+IDEA+for+Eclipse+Users" + class="external-link">IntelliJ IDEA for Eclipse users</a></li> + <li><a href="{@docRoot}tools/studio/index.html">Android Studio Overview</a></li> </ul> </div> </div> -<p>If you have been using <a href="{@docRoot}tools/help/adt.html">Eclipse with ADT</a>, be aware -that <a href="{@docRoot}tools/studio/index.html">Android Studio</a> is now the official IDE for -Android, so you should migrate to Android Studio to receive all the latest IDE updates.</p> +<p>Migrating from Eclipse ADT to Android Studio requires adapting to a new project structure, +build system, and IDE functionality. To simplify the migration process, Android Studio provides an +import tool so you can quickly transition your Eclipse ADT workspaces and Ant build scripts to +Android Studio projects and <a href="http://www.gradle.org">Gradle</a>-based build files.</p> -<p>To migrate existing Android projects, simply import them using Android Studio:</p> +<p>This document provides an overview of the migration process and walks you +through a sample import procedure. For more information about Android Studio features and the +Gradle-based build system, see <a href="{@docRoot}tools/studio/index.html">Android Studio Overview</a> +and <a href="{@docRoot}tools/building/configuring-gradle.html">Configuring Gradle Builds</a>.</p> -<ol> - <li>In Android Studio, from the main menu or the <strong>Welcome to Android Studio</strong> page, - choose <strong>File > Import Project</strong>.</li> - <li> Select the Eclipse root project directory</strong> and click <strong>OK</strong>. - <p class="note"><strong>Note:</strong> The Eclipse root directory must contain the - <code>AndroidManifest.xml</code> file. Also, the root directory must contain either the - <code>.project</code> and <strong>.classpath</strong> files from Eclipse or the - <code>res/</code> and <code>src/</code> directories.</p> + + +<h2 id="overview">Migration Overview </h2> +<p>Migrating from Eclipse to Android Studio requires that you change the structure of your +development projects, move to a new build system, and use a new user interface. Here are some of +the key changes you should be aware of as you prepare to migrate to Android Studio:</p> +<ul> + <li><strong>Project files</strong> + <p>Android Studio uses a different project structure. Each Eclipse ADT + project is called a module in Android Studio. Each instance of Android + Studio contains a project with one or more app modules. For more information see, + <a href="{@docRoot}tools/studio/eclipse-migration-guide.html#project-structure">Project + Structure</a>.</p></li> + + <li><strong>Manifest settings</strong> + <p>Several elements in the <code>AndroidManifest.xml</code> file are now properties in the + <code>defaultConfig</code> and <code>productFlavors</code> blocks in the + <code>build.gradle</code> file. These elements are still valid manifest entries and may + appear in manifests from older projects, imported projects, dependencies, and libraries. For + more information see, + <a href="{@docRoot}tools/studio/eclipse-migration-guide.html#manifest-settings">Manifest + Settings</a>.</p></li> + + <li><strong>Dependencies</strong> + <p>Library dependencies are handled differently in Android Studio, using Gradle dependency + declarations and Maven dependencies for well-known local source and binary libraries with + Maven coordinates. For more information see, + <a href="{@docRoot}tools/studio/eclipse-migration-guide.html#dependencies">Dependencies</a></p> + </li> + + <li><strong>Test code</strong> + <p>With Eclipse ADT, test code is written in separate projects and integrated through the + <code><instrumentation></code> element in your manifest file. Android Studio provides a + <code>AndroidTest</code> folder within your project so you can easily add and maintain your test + code within the same project view. JUnit tests can also be configured to run locally to reduce + testing cycles.</p></li> + + <li><strong>Gradle-based build system</strong> + <p>In place of XML-based Ant build files, Android Studio supports Gradle build files, which + use the Gradle Domain Specific Language (DSL) for ease of extensibility and customization. + The Android Studio build system also supports + <a href="{@docRoot}tools/building/configuring-gradle.html#workBuildVariants"> build variants</a>, + which are combinations of <code>productFlavor</code> and <code>buildTypes</code>, to customize + your build outputs.</p></li> + + <li><strong>User interface</strong> + <p>Android Studio provides an intuitive interface and menu options based on the + <a class="external-link" href="https://www.jetbrains.com/idea/" target="_blank">IntelliJ IDEA</a> + IDE. To become familiar with the IDE basics, such as navigation, code completion, and keyboard + shortcuts, see + <a class="external-link" href="https://www.jetbrains.com/idea/help/intellij-idea-quick-start-guide.html" + target="_blank">IntelliJ IDEA Quick Start Guide</a>.</p></li> + + <li><strong>Developer tools versioning</strong> + <p>Android Studio updates independently of the Gradle-based build system so different build + settings can be applied across different versions of command line, Android Studio, and + continuous integration builds. For more information, see + <a href="{@docRoot}tools/building/configuring-gradle.html">Configuring Gradle Builds</a>.</p> + </li> +</ul> + + + + +<h2 id="prerequisites">Migration Prerequisites</h2> +<p>Before migrating your Eclipse ADT app to Android Studio, review the following steps to make +sure your project is ready for conversion, and verify you have the tool configuration you need in +Android Studio:</p> + +<ul> + <li>In Eclipse ADT: + <ul> + <li>Make sure the Eclipse ADT root directory contains the <code>AndroidManifest.xml</code> + file. Also, the root directory must contain either the <code>.project</code> and + <code>.classpath</code> files from Eclipse or the <code>res/</code> and <code>src/</code> + directories.</li> + <li>Build your project to ensure your latest workspace and project updates are saved and + included in the import.</li> + <li>Comment out any references to Eclipse ADT workspace library files in the + <code>project.properties</code> or <code>.classpath</code> files for import. You can + add these references in the <code>build.gradle</code> file after the import. For more + information, see + <a href="{@docRoot}tools/building/configuring-gradle.html">Configuring Gradle Builds</a>.</li> + <li>It may be useful to record your workspace directory, path variables, and any actual path + maps that could be used to specify any unresolved relative paths, path variables, and + linked resource references. Android Studio allows you to manually specify any unresolved + paths during the import process.</li> + </ul> + </li> + <li>In Android Studio: + <ul> + <li>Make a note of any third-party Eclipse ADT plugins in use and check for equivalent features + in Android Studio or search for a compatible plugin in the + <a href="https://plugins.jetbrains.com/?androidstudio" class="external-link">IntelliJ Android + Studio Plugins</a> repository. Use the <strong>File > Settings > Plugins</strong> menu + option to manage plugins in Android Studio. Android Studio does not migrate any third-party + Eclipse ADT plugins.</li> + <li>If you plan to run Android Studio behind a firewall, be sure to set the proxy settings for + Android Studio and the SDK Manager. Android Studio requires an internet connection for + Setup Wizard synchronization, 3rd-party library access, access to remote repositories, + <a href="http://www.gradle.org" class="external-link">Gradle</a> + initialization and synchronization, and Android Studio version updates. For more information, + see <a href="{@docRoot}tools/studio/index.html#proxy">Proxy Settings</a>.</li> + <li>Use the <strong>File > Settings > System Settings</strong> menu option to verify the + current version and, if necessary, update Android Studio to the latest version from the + stable channel. To install Android Studio, please visit the + <a href="{@docRoot}sdk/index.html">Android Studio download page</a>.</li> + </ul> </li> - <li>Follow the steps in the import wizard. </li> + </ul> + + + +<h2 id="migrate">Importing Projects to Android Studio</h2> +<p>Android Studio provides a function for importing Eclipse ADT projects, which creates a new +Android Studio project and app modules based on your current +Eclipse ADT workspace and projects. No changes are made to your Eclipse project files. The Eclipse +ADT workspace becomes a new Android Studio project, and each Eclipse ADT project within the workspace +becomes a new Android Studio module. Each instance of Android Studio contains a project with one or +more app modules.</p> + +<p>After selecting an Eclipse ADT project to import, Android Studio creates the Android +Studio project structure and app modules, generates the new Gradle-based build files and settings, +and configures the required dependencies. The import options also allow you to enter your workspace +directory and any actual path maps to handle any unresolved relative paths, path variables, and +linked resource references.</p> + +<p>Depending on the structure of your Eclipse ADT development project, you should select specific +files for importing:</p> +<ul> +<li>For workspaces with multiple projects, select the project folder for each Eclipse ADT + project individually to import the projects into the same Android Studio project. Android + Studio combines the Eclipse ADT projects into a single Android Studio project with different app + modules for each imported project.</li> + +<li>For Eclipse ADT projects with separate test projects, select the test project folder for + import. Android Studio imports the test project and then follows the dependency chain to import + the source project and any project dependencies.</li> + + <li>If Eclipse ADT projects share dependencies within the same workspace, import each + project individually into Android Studio. Android Studio maintains the shared dependencies + across the newly created modules as part of the import process.</li> +</ul> + +<p>To import a project to Android Studio:</p> + +<ol> + <li>Start Android Studio and close any open Android Studio projects.</li> + <li>From the Android Studio menu select <strong>File > New > Import Project</strong>. + <p>Alternatively, from the <em>Welcome</em> screen, select <strong>Import project + (Eclipse ADT, Gradle, etc.)</strong>.</p></li> + <li>Select the Eclipse ADT project folder with the <code>AndroidManifest.xml</code> file + and click <strong>Ok</strong>. + <p> <img src="{@docRoot}images/tools/studio-select-project-forimport.png" alt="" /></p> + </li> + <li>Select the destination folder and click <strong>Next</strong>. + <p> <img src="{@docRoot}images/tools/studio-import-destination-dir.png" alt="" /></p></li> + <li>Select the import options and click <strong>Finish</strong>. + <p>The import process prompts to migrate any library and project dependencies to Android Studio, + and add the dependency declarations to the <code>build.gradle</code> file. The import process + also 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. The import options also allow you to enter your workspace directory and any actual + path maps to handle any unresolved relative paths, path variables, and linked resource + references.</p> + <p> <img src="{@docRoot}images/tools/studio-import-options.png" alt="" /></p></li> + + <li>Android Studio imports the app and displays the project import summary. Review the summary + for details about the project restructuring and the import process. + <p> <img src="{@docRoot}images/tools/studio-import-summary.png"/></p> + </li> </ol> -<p>Android Studio imports the current dependencies, downloads libraries, and -creates an Android Studio project with the imported Eclipse project as the main module. Android -Studio also creates the required Gradle build files. </p> +<p>After importing the project from Eclipse ADT to the new Android Studio project and module +structure, each app module folder in Android Studio contains the complete source set for that +module, including the {@code src/main} and {@code src/androidTest} directories, resources, build +file, and Android manifest. Before starting app development, you should resolve any issues shown in +the project import summary to make sure the project re-structuring and import process completed +properly.</p> + + + +<h3 id="post-migration">Validating imported projects</h3> +<p>After completing the import process, use the Android Studio <strong>Build</strong> and +<strong>Run</strong> menu options to build your project and verify the output. If your project +is not building properly, check the following settings:</p> + +<ul> +<ul> + <li>Use the <strong>Android SDK</strong> button in Android Studio to launch the <a href= + "{@docRoot}tools/help/sdk-manager.html">SDK Manager</a> and verify the installed versions of SDK + tools, build tools, and platform match the settings for your Eclipse ADT project. Android Studio + inherits the SDK Manager and JDK settings from your imported Eclipse project. + </li> + <li>Use the <strong>File > Project Structure</strong> menu option to verify additional + Android Studio settings: + <ul> + <li>Under <em>SDK Location</em> verify Android Studio has access to the correct SDK and + JDK locations and versions. </li> + <li>Under <em>Project</em> verify the Gradle version, Android Plugin version, and related + repositories.</li> + <li>Under <em>Modules</em> verify the app and module settings, such as signing configuration + and library dependencies. </li> + </ul> + </li> + <li>If your project depends on another project, make sure that dependency is defined properly in + the <code>build.gradle</code> file in the app module folder.</li> +</ul> + -<p>The import process replaces any JAR files and libraries with Gradle dependencies, and replaces -source libraries and binary libraries with Maven dependencies, so you no longer need to maintain -these files manually.</p> +<p>If there still are unexpected issues when building and running your project in Android +Studio after you have checked these settings, consider modifying the Eclipse ADT project and +re-starting the import process. Importing an Eclipse ADT project to Android Studio creates a new +Android Studio project and does not impact the existing Eclipse ADT project. </p> - <p class="note"><strong>Note:</strong> If there are references to Eclipse workspace library files, - comment them out in the <code>project.properties</code> or <code>.classpath</code> files - that you imported from the Eclipse project. You can then add these files in the - <code>build.gradle</code> file. See - <a href="{@docRoot}tools/building/configuring-gradle.html">Configuring Gradle Builds</a>. </p> -<p>For more help getting started with Android Studio and the IntelliJ user experience, -<a href="{@docRoot}tools/studio/index.html">learn more about Android Studio</a> and -read <a href="http://confluence.jetbrains.com/display/IntelliJIDEA/FAQ+on+Migrating+to+IntelliJ+IDEA" - class="external-link">FAQ on Migrating to IntelliJ IDEA</a>.</p> +<p>To get started using Android Studio, review the +<a href="{@docRoot}tools/studio/index.html">Android Studio</a> features and +<a href="http://www.gradle.org">Gradle</a>-based build system to become familiar with the new +project and module structure, flexible build settings, and other advanced Android development +capabilities. For a comparison of Eclipse ADT and Android Studio features and usage, see +<a href="{@docRoot}tools/studio/eclipse-migration-guide.html">Transitioning to Android Studio from +Eclipse</a>. For specific Android Studio how-to documentation, see the pages in the +<a href="{@docRoot}tools/workflow/index.html">Workflow</a> section. +</p> diff --git a/docs/html/support.jd b/docs/html/support.jd index bbed7df..94d6478 100644 --- a/docs/html/support.jd +++ b/docs/html/support.jd @@ -8,80 +8,96 @@ page.image=/images/android-support-card.png <div class="wrap" style="width:940px;"> - <h1>Developer Support Resources</h1> -<!-- -<p>A variety of support resources are available to help you report and resolve issues while you are developing apps for Android. </p> ---> - <div style="margin: 20px 0 0;"> - - <div class="col-8" style="margin-left:0"> - <h3 style="font-size: 14px;line-height: 21px;color: #555;text-transform: uppercase;border-bottom: 1px solid #CCC;margin: 0 0 20px;">Code-Level Support</h3> - -<h5>Community and Office Hours</h5> -<p style="color:#888"> - -<a href="https://plus.google.com/+AndroidDevelopers">Android Developers</a> on Google+<br /> -<a href="https://plus.google.com/communities/105153134372062985968">Android Development community</a> on Google+<br /> -<a href="http://groups.google.com/group/android-developers">android-developers</a> support forum<br /> -<a href="http://groups.google.com/group/android-ndk">android-ndk</a> support forum<br /> -<a href="http://groups.google.com/group/android-security-discuss">android-security-discuss</a> support forum<br /> - - <a href="http://webchat.freenode.net/?channels=android">#android</a>, <a href="http://webchat.freenode.net/?channels=android-dev">#android-dev</a> <span style="color:#888">(IRC via irc.freenode.net)</span><br /> -</p> - -<p><b> -<a target="_blank" -href="https://helpouts.google.com/partner/ask?vertical=programming&tags=android&origin=http:%2F%2Fdeveloper.android.com%2Fsupport.html">Ask a question in Google Helpouts</a> -</b></p> - - -<h5>Send Feedback</h5> -<p> - <a href="http://code.google.com/p/android/issues/entry?template=Developer%20Documentation">Report documentation bug</a><br /> - <a href="https://code.google.com/p/android/issues/entry?template=User%20bug%20report">Report device bug</a><br /> - <a href="https://code.google.com/p/android/issues/entry?template=Developer%20bug%20report">Report platform bug</a><br /> -</p> - - - </div> - - - - <div class="col-8" style="margin-right:0"> - <h3 style="font-size: 14px;line-height: 21px;color: #555;text-transform: -uppercase;border-bottom: 1px solid #CCC;margin: 0 0 20px;">Google Play Support</h3> -<h5>Help center</h5> -<p style="color:#888"> - <a href="http://support.google.com/googleplay/android-developer/">Help Center Home</a><br /> - <a href="http://support.google.com/googleplay/android-developer/bin/static.py?hl=en&page=known_issues.cs">Known Issues</a><br /> -</p> - -<h5 id="contact">Direct support contacts for developers</h5> -<p style="color:#888"> - <a href=" https://support.google.com/googleplay/android-developer/troubleshooter/3049653">Registration, account issues</a><br /> - <a href="https://support.google.com/googleplay/android-developer/troubleshooter/3055196">Publishing, app distribution issues</a><br /> - <a href="https://support.google.com/googleplay/android-developer/troubleshooter/3055329">App visibility and discoverability</a><br /> - <a href="https://support.google.com/googleplay/android-developer/troubleshooter/3076003">Billing and reporting</a><br /> - <a href="http://support.google.com/googleplay/android-developer/bin/request.py?contact_type=takedown">Inappropriate apps</a><br /> - <a href="http://support.google.com/googleplay/android-developer/bin/answer.py?hl=en&answer=1085703&topic=15868&ctx=topic">Report a Google Play policy violation</a> -</p> - -<h5>End-user support</h5> -<p style="color:#888"> - <a href="http://support.google.com/googleplay/bin/request.py?contact_type=contact_policy&policy=apps">Click-to-call and email support for Google Play end users</a><br /> -</p> - - - - <h5>Payment and Merchant Issues</h5> - -<p style="color:#888;margin-bottom:1.5em;"> - <a href="http://support.google.com/checkout/sell/">Merchant Help Center Home<br /> - <a href="http://support.google.com/checkout/sell/bin/static.py?hl=en&page=ts.cs&ts=2472700">Issue reporting tool<br /> - <a href="https://productforums.google.com/forum/#!forum/checkout-merchant">checkout-merchant</a> support forum<br /> - <a href="http://support.google.com/googleplay/android-developer/bin/request.py?contact_type=survey">Feedback survey</a> -</p> +<h1>Developer Support Resources</h1> + +<div style="margin: 20px 0 0;"> + +<div class="col-8" style="margin-left:0"> + + <h3 style="font-size: 14px;line-height: 21px;color: #555;text-transform: + uppercase;border-bottom: 1px solid #CCC;margin: 0 0 20px;"> + Code-Level Support</h3> + + <h5>Community Resources</h5> + <p style="color:#888"> + + <a href="https://plus.google.com/+AndroidDevelopers"> + Android Developers</a> on Google+<br /> + <a href="https://plus.google.com/communities/105153134372062985968"> + Android Development community</a> on Google+<br /> + <a href="http://groups.google.com/group/android-developers"> + android-developers</a> support forum<br /> + <a href="http://groups.google.com/group/android-ndk"> + android-ndk</a> support forum<br /> + <a href="http://groups.google.com/group/android-security-discuss"> + android-security-discuss</a> support forum<br /> + + <a href="http://webchat.freenode.net/?channels=android">#android</a>, + <a href="http://webchat.freenode.net/?channels=android-dev">#android-dev</a> + <span style="color:#888">(IRC via irc.freenode.net)</span><br /> + </p> + + + <h5>Send Feedback</h5> + <p> + <a href="http://code.google.com/p/android/issues/entry?template=Developer%20Documentation"> + Report documentation bug</a><br /> + <a href="https://code.google.com/p/android/issues/entry?template=User%20bug%20report"> + Report device bug</a><br /> + <a href="https://code.google.com/p/android/issues/entry?template=Developer%20bug%20report"> + Report platform bug</a><br /> + </p> </div> + + + +<div class="col-8" style="margin-right:0"> + <h3 style="font-size: 14px;line-height: 21px;color: #555;text-transform: + uppercase;border-bottom: 1px solid #CCC;margin: 0 0 20px;"> + Google Play Support</h3> + + <h5>Help center</h5> + <p> + <a href="http://support.google.com/googleplay/android-developer/">Help Center Home</a><br /> + </p> + + <h5 id="contact">Direct support contacts for developers</h5> + <p> + <a href=" https://support.google.com/googleplay/android-developer/troubleshooter/3049653"> + Registration, account issues</a><br /> + <a href="https://support.google.com/googleplay/android-developer/troubleshooter/3055196"> + Publishing, app distribution issues</a><br /> + <a href="https://support.google.com/googleplay/android-developer/troubleshooter/3055329"> + App visibility and discoverability</a><br /> + <a href="https://support.google.com/googleplay/android-developer/troubleshooter/3076003"> + Billing and reporting</a><br /> + <a href="http://support.google.com/googleplay/android-developer/bin/request.py?contact_type=takedown"> + Inappropriate apps</a><br /> + <a href="http://support.google.com/googleplay/android-developer/bin/answer.py?hl=en&answer=1085703&topic=15868&ctx=topic"> + Report a Google Play policy violation</a> + </p> + + <h5>End-user support</h5> + <p> + <a href="http://support.google.com/googleplay/bin/request.py?contact_type=contact_policy&policy=apps"> + Support for Google Play end users</a><br /> + </p> + + + + <h5>Payment and Merchant Issues</h5> + + <p style="margin-bottom:1.5em;"> + <a href="http://support.google.com/checkout/sell/"> + Merchant Help Center Home<br /> + <a href="http://support.google.com/googleplay/android-developer/bin/request.py?contact_type=survey"> + Feedback survey</a> + </p> + + </div> + +</div> <!-- end margin: 20px --> +</div> <!-- end class:wrap --> diff --git a/docs/html/tools/building/building-cmdline-ant.jd b/docs/html/tools/building/building-cmdline-ant.jd index 51158de..add6ca2 100644 --- a/docs/html/tools/building/building-cmdline-ant.jd +++ b/docs/html/tools/building/building-cmdline-ant.jd @@ -31,6 +31,14 @@ Emulator</a></li> </div> </div> +<p class="caution"> + <strong>Important:</strong> Support for Ant as a build tool for Android is ending, per our + <a href="http://android-developers.blogspot.com/2015/06/an-update-on-eclipse-android-developer.html" + class="external-link">announcement</a>. You should migrate your app development projects to + Android Studio and Gradle as soon as possible. For more information on transitioning to these + tools, see <a href="{@docRoot}sdk/installing/migrate.html">Migrating to Android Studio</a>. +</p> + <p>There are two ways to build your application using the Ant build script: one for testing/debugging your application — <em>debug mode</em> — and one for building your final package for release — <em>release mode</em>. Regardless of which way you build your application, diff --git a/docs/html/tools/building/manifest-merge.jd b/docs/html/tools/building/manifest-merge.jd new file mode 100644 index 0000000..54166ec --- /dev/null +++ b/docs/html/tools/building/manifest-merge.jd @@ -0,0 +1,510 @@ +page.title=Manifest Merging +@jd:body + +<div id="qv-wrapper"> +<div id="qv"> + + <h2>In this document</h2> + <ol> + <li><a href="#merge-rules">Merge Conflict Rules</a></li> + <li><a href="#markers-selectors">Merge Conflict Markers and Selectors</a></li> + <li><a href="#inject-values">Injecting Build Values into a Manifest</a></li> + <li><a href="#merge-prodflavorsGroups">Manifest Merging Across Product Flavor Groups</a></li> + <li><a href="#implicit-permissions">Implicit Permissions</a></li> + <li><a href="#merge-errors">Handling Manifest Merge Build Errors</a></li> + </ol> + + <h2>See also</h2> + <ol> + <li><a href="{@docRoot}sdk/installing/studio-build.html">Build System Overview</a></li> + <li><a href="{@docRoot}tools/building/configuring-gradle.html">Configuring Gradle Builds</a> </li> + </ol> + +</div> +</div> + + +<p>With Android Studio and <a href="http://www.gradle.org">Gradle</a>-based builds, each app can +contain manifest files in multiple locations, such as the <code>src/main/</code> folder for +the <code>productFlavor</code>, libraries, Android ARchive (AAR) bundles of Android Library +projects, and dependencies. During the build process, manifest merging combines the settings from +the various <code>AndroidManifest.xml</code> 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 +<a href="{@docRoot}tools/building/configuring-gradle.html#workBuildVariants">build variant</a>.</p> + + +<h2 id="merge-rules">Merge Conflict Rules</h2> +<p>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. +<a href="#markers-selectors">Conflict markers and selectors</a> can also define custom merge rules, +such as allowing an imported library to have a <code>minSdkVersion</code> higher than the +version defined in the other higher priority manifests. </p> + +<p>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:</p> + +<ul> + <li>Highest priority: <code>buildType</code> manifest settings </li> + <li>Higher priority: <code>productFlavor</code> manifest settings </li> + <li>Medium priority: Manifests in the <code>src/main/</code> directory of an app project</li> + <li>Low priority: Dependency and library manifest settings </li> +</ul> + +<p>Manifest merge conflicts are resolved at the XML node and +attribute levels based on the following merge rules. </p> + +<table> + <tr> + <th scope="col">High Priority Element</th> + <th scope="col">Low Priority Element</th> + <th scope="col">Manifest Merge Result</th> + </tr> + <tr> + <td rowspan="3">no attribute</td> + <td>no attribute</td> + <td>no attribute</td> + </tr> + <tr> + + <td>attribute set to default</td> + <td>default attribute</td> + </tr> + <tr> + + <td>attribute set to non-default </td> + <td>low priority attribute</td> + </tr> + <tr> + <td>attribute set to default</td> + <td rowspan="2">no attribute</td> + <td>default attribute</td> + </tr> + <tr> + <td>attribute set to non-default </td> + + <td>high priority attribute</td> + </tr> + <tr> + <td>attribute set to default</td> + <td>attribute set to default</td> + <td>default attribute</td> + </tr> + <tr> + <td>attribute set to default</td> + <td>attribute set to non-default </td> + <td>low priority attribute</td> + </tr> + <tr> + <td>attribute set to non-default</td> + <td>attribute set to default</td> + <td>high priority attribute</td> + </tr> + <tr> + <td>attribute set to non-default</td> + <td>attribute set to non-default </td> + <td>Merge if settings match, otherwise causes conflict error.</td> + </tr> + </table> + + + +<p>Exceptions to the manifest merge rules: </p> + +<ul> + <li>The <code>uses-feature android:required;</code> and + <code>uses-library android:required</code> elements default to <code>true</code> and use + an <em>OR</em> merge so that any required feature or library is included in the generated APK. </li> + + <li>If not declared, the + <a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html"><code><uses-sdk></code></a> + elements, <code>minSdkVersion</code> and + <code>targetSdkVersion</code>, default to a value of 1. When + merge conflicts occur, the value in the higher priority manifest version is used.</li> + + <li>Importing a library with a <code>minSdkVersion</code> value higher than the app's + <code>src/main/</code> manifest manifest generates an error unless + the <code>overrideLibrary</code> conflict marker is used. + + <p class="note"><strong>Note:</strong> If not explicitly declared, the <code>targetSdkVersion</code> + defaults to the <code>minSdkVersion</code> value. When no <code><uses-sdk></code> element is + present in any manifest or the <code>build.gradle</code> file, the + <code>minSdkVersion</code> defaults to 1.</p> </li> + + <li>When importing a library with a <code>targetSdkVersion</code> value lower than the app's + <code>src/main/</code> manifest, the manifest merge + process explicitly grants permissions and ensures that the imported library functions properly. </li> + + <li>The <code>manifest</code> element only merges with child manifest elements. </li> + + <li>The <code>intent-filter</code> element is never changed and is always added to the common + parent node in the merged manifest. </li> +</ul> + +<p class="caution"><strong>Important:</strong> After the manifests are merged, the build process +overrides the final manifest settings with any settings that are also in the +<code>build.gradle</code> file. For more details, see +<a href="{@docRoot}tools/building/configuring-gradle.html">Configuring Gradle Builds</a>. </p> + + + +<h2 id="markers-selectors">Merge Conflict Markers and Selectors</h2> +<p>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 <code>minSdkVersion</code> value than the higher priority +manifest, or to merge manifests with the same activity but different <code>android:theme</code> +values. </p> + +<h3 id="conflict-markers">Merge Conflict Markers</h3> +<p>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:</p> + +<dl> + <dt><code>merge</code></dt> + <dd>Merges attributes when there are no conflicts with the merge rules. The default merge + action.</dd> + <dt><code>replace</code></dt> + <dd>Replaces attributes in the lower priority manifest with those from the higher priority + manifest.</dd> + <dt><code>strict</code></dt> + <dd>Sets the merge policy level so that merged elements with same attributes, but different + values generate a build failure, unless resolved through the conflict rules.</dd> + <dt><code>merge-only</code></dt> + <dd>Allows merge actions for only lower priority attributes.</dd> + <dt><code>remove</code></dt> + <dd>Removes the specified lower priority element from the merged manifest.</dd> + <dt><code>remove-All</code></dt> + <dd>Removes all lower priority elements of the same node type from the merged manifest.</dd> +</dl> + + +<p>By default, the manifest merge process applies the <code>merge</code> conflict marker to +the node level. All declared manifest attributes default to a <code>strict</code> +merging policy. </p> + +<p>To set a merge conflict marker, first declare the namespace in the +<code>AndroidManifest.xml</code> file. Then, enter the merge conflict marker in the manifest to +specify a custom merge conflict action. This example inserts the <code>replace</code> marker to +set a replace action to resolve conflicts between the <code>android:icon</code> and +<code>android:label</code> manifest elements. </p> + +<pre> + +<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"> + ... + +</manifest> + +</pre> + + +<h4>Marker attributes</h4> +<p>Conflict markers use <code>tools:node</code> and <code>tools:attr</code> attributes to +restrict merge actions at the XML node or attribute level. </p> + +<p>The <code>tools:attr</code> markers use only the <code>restrict</code>, <code>remove</code>, and +<code>replace</code> merge actions. Multiple <code>tools:attr</code> marker values can be applied +to a specific element. For example, use <code>tools:replace="icon, label, theme"</code> to replace +lower priority <code>icon</code>, <code>label</code>, and <code>theme</code> attributes. </p> + + +<h4>Merge conflict marker for imported libraries</h4> +<p>The <code>overrideLibrary</code> conflict marker applies to the <code><uses-sdk></code> +manifest declaration and is used to import a library even though the library's +<code><uses-sdk></code> values, such as <code>minSdkVersion</code> +are set to different values than those in the other higher priority manifests. </p> + +<p>Without this marker, library manifest merge conflicts from the +<code><uses-sdk></code> values cause the merge process to fail.</p> + +<p>This example applies the <code>overrideLibrary</code> conflict marker to resolve the merge +conflict between <code>minSdkVersion</code> values in the <code>src/main/</code> manifest and an +imported library manifest. + + +<p><code>src/main/</code> manifest: </p> +<pre> +<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"/> + ... +</pre> + +<p>Library manifest: </p> + +<pre> +<manifest xmlns:android="http://schemas.android.com/apk/res/android" + package="com.example.lib1"> + ... + <uses-sdk android:minSdkVersion="4" /> + ... + </manifest> +</pre> + +<p class="note"><strong>Note:</strong> The default merge process does not allow importing a library +with a higher <code>minSdkVersion</code> than the app's <code>src/main/</code> manifest unless +the <code>overrideLibrary</code> conflict marker is used. </p> + + + +<h3 id="marker-selectors">Marker Selectors</h3> +<p>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.</p> + +<p>This example uses the <code>tools:node</code> marker to remove the <code>permisionOne</code> +attribute, while the <code>tools:selector</code> selector specifies the specific library as +<em>com.example.lib1</em>. The <code>permisionOne</code> permission is filtered from only the +<code>lib1</code> library manifests. </p> + +<pre> +<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"> + ... +</pre> + + + +<h2 id="inject-values">Injecting Build Values into a Manifest</h2> +<p>Manifest merging can also be configured to use manifest placeholders to inject +property values from the <code>build.gradle</code> file into the manifest attributes. </p> + +<p>Manifest placeholders use the syntax <code>${name}</code> for attribute values, where +<code>name</code> is the injected <code>build.gradle</code> property. The <code>build.gradle</code> +file uses the <code>manifestPlaceholders</code> property to define the placeholder values. </p> + +<p class="note"><strong>Note:</strong> 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.</p> + +<p>This example shows the manifest placeholder <code>${applicationId}</code> used to inject the +<code>build.gradle</code> <code>applicationId</code> property value in to <code>android:name</code> +attribute value. </p> + +<p class="note"><strong>Note:</strong> Android Studio provides a default +<code>${applicationId}</code> placeholder for the <code>build.gradle</code> +<code>applicationId</code> value that is not shown in the build file.</p> + + +<p>Manifest entry:</p> + +<pre> + +<activity +android:name=".Main"> + <intent-filter> + <action android:name="${applicationId}.foo"> + </action> +</intent-filter> +</activity> + +</pre> + + +<p>Gradle build file:</p> + +<pre> +android { + compileSdkVersion 22 + buildToolsVersion "22.0.1" + + productFlavors { + flavor1 { + applicationId = "com.mycompany.myapplication.productFlavor1" + } +} + +</pre> + +<p>Merged manifest value: </p> + +<pre> +<action android:name="com.mycompany.myapplication.productFlavor1.foo"> +</pre> + + +<p>The manifest placeholder syntax and build file <code>manifestPlaceholders</code> +property can be used to inject other manifest values. For properties other than the +<code>applicationId</code>, the <code>manifestPlaceholders</code> property is explicitly declared +in the <code>build.gradle</code> file. This example shows the manifest placeholder for injecting +<code>activityLabel</code> values.</p> + +<p>Gradle build file: </p> + +<pre> +android { + defaultConfig { + manifestPlaceholders = [ activityLabel:"defaultName"] + } + productFlavors { + free { + } + pro { + manifestPlaceholders = [ activityLabel:"proName" ] + } + } + +</pre> + +<p>Placeholder in the manifest file: </p> + +<pre> +<activity android:name=".MainActivity" android:label="${activityLabel}" > +</pre> + +<p class="note"><strong>Note:</strong> The placeholder value supports partial value injection, +for example <code>android:authority="com.acme.${localApplicationId}.foo"</code>. </p> + + + +<h2 id="merge-prodflavorsGroups">Manifest Merging Across Product Flavor Groups</h2> + +<p>When using the <code>GroupableProductFlavor</code> 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. </p> + +<p>For example, if a build variant references the product flavors <code>x86</code>, +<code>mdpi</code>, <code>21</code>, and <code>paid</code> from the respective product flavor +groups <code>ABI</code>, <code>Density</code>, <code>API</code>, and <code>Prod</code>, listed +in this order in the <code>build.gradle</code> 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.</p> + +<p>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. </p> +<table> + <tr> + <th scope="col">Product Flavor Group</th> + <th scope="col">Product Flavor</th> + <tr> + <td>ABI</td> + <td>x86</td> + </tr> + <tr> + <td>density</td> + <td>mdpi</td> + </tr> + <tr> + <td>API</td> + <td>22</td> + </tr> + <tr> + <td>prod</td> + <td>paid</td> + </tr> +</table> + +<p>Manifest merge order:</p> + + <ul> + <li>prod-paid AndroidManifest.xml (lowest priority) merges into API-22 AndroidManifest.xml</li> + <li>API-22 AndroidManifest.xml merges into density-mpi AndroidManifest.xml</li> + <li>density-mpi AndroidManifest.xml merges into ABI-x86 AndroidManifest.xml (highest priority)</li> + </ul> + + +<h2 id="implicit-permissions">Implicit Permissions</h2> +<p>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 <code>targetSdkVersion</code> of 16 imports a library with a +<code>targetSdkVersion</code> of 2, Android Studio adds the <code>WRITE_EXTERNAL_STORAGE</code> +permission to ensure permission compatibility across the SDK versions. + +<p class="note"><strong>Note:</strong> More recent Android releases replace implicit +permissions with permission declarations.</p> + + +This table lists the importing library versions and the declared permissions. +</p> + + <table> + <tr> + <th>Importing this library version</th> + <th>Declares this permission in the manifest </th> + </tr> + <tr> + <td><code>targetSdkVersion</code> < 2 </td> + <td><code>WRITE_EXTERNAL_STORAGE</code> </td> + </tr> + <tr> + <td><code>targetSdkVersion</code> < 4 </td> + <td><code>WRITE_EXTERNAL_STORAGE</code>, <code>READ_PHONE_STATE</code> </td> + </tr> + <tr> + <td>Declared <code>WRITE_EXTERNAL_STORAGE</code></td> + <td><code>READ_EXTERNAL_STORAGE</code></td> + </tr> + <tr> + <td><code>targetSdkVersion</code> < 16 and using the <code>READ_CONTACTS</code> + permission</td> + <td><code>READ_CALL_LOG</code></td> + </tr> + <tr> + <td><code>targetSdkVersion</code> < 16 and using the <code>WRITE_CONTACTS</code> + permission</td> + <td><code>WRITE_CALL_LOG</code></td> + </tr> + </table> + + + +<h2 id="merge-errors">Handling Manifest Merge Build Errors</h2> +<p>During the build process, the manifest merge process stores a record of each merge transaction +in the <code>manifest-merger-<productFlavor>-report.txt</code> file in the module +<code>build/outputs/logs</code> folder. A different log file is generated for each of the +module's build variants. </p> + +<p>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 +<code>android:screenOrientation</code> merge conflict between the following manifests causes +a build error. </p> + +<p>Higher priority manifest declaration: </p> + +<pre> +<activity + android:name="com.foo.bar.ActivityOne" + android:screenOrientation="portrait" + android:theme="@theme1"/> +</pre> + +<p>Lower priority manifest declaration: </p> + +<pre> +<activity + android:name="com.foo.bar.ActivityOne" + android:screenOrientation="landscape"/> +</pre> + +<p>Error log:</p> + +<pre> +/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 <activity> element at AndroidManifest.xml:1:5 to override +</pre> + + diff --git a/docs/html/tools/help/adb.jd b/docs/html/tools/help/adb.jd index 41c6686..641d463 100644 --- a/docs/html/tools/help/adb.jd +++ b/docs/html/tools/help/adb.jd @@ -16,18 +16,7 @@ page.tags=adb <li><a href="#move">Installing an Application</a></li> <li><a href="#forwardports">Forwarding Ports</a></li> <li><a href="#copyfiles">Copying Files to or from an Emulator/Device Instance</a></li> - <li><a href="#shellcommands">Issuing Shell Commands</a> - <ol> - <li><a href="#am">Using activity manager (am)</a></li> - <li><a href="#pm">Using package manager (pm)</a></li> - <li><a href="#sqlite">Examining sqlite3 databases from a remote shell</a></li> - <li><a href="#screenrecord">Recording a device screen</a></li> - <li><a href="#monkey">UI/Application Exerciser Monkey</a></li> - <li><a href="#othershellcommands">Other shell commands</a></li> - </ol> - </li> - <li><a href="#logcat">Enabling logcat logging</a></li> - <li><a href="#stopping">Stopping the adb server</a></li> + <li><a href="#stopping">Stopping the adb Server</a></li> <li><a href="#wireless">Wireless usage</a></li> </ol> @@ -279,7 +268,7 @@ would issue the <code>install</code> command as soon as the emulator or device i <td rowspan="2">Shell</td> <td><code>shell</code></td> <td>Starts a remote shell in the target emulator/device instance.</td> -<td rowspan="2">See <a href="#shellcommands">Issuing Shell Commands</a> for more information. </td> +<td rowspan="2">See <a href="{@docRoot}tools/help/shell.html#shellcommands">ADB Shell Commands</a> for more information. </td> </tr> <tr> @@ -412,950 +401,10 @@ emulator/device instance (remote). For example: </p> +<h2 id="stopping">Stopping the adb Server</h2> - - - - -<h2 id="shellcommands">Issuing Shell Commands</h2> - -<p>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 <code>/system/bin/...</code> - -<p>Two of the most common command tools are <a href="#am">activity manager</a> ({@code am}) and -<a href="#pm">package manager</a> ({@code pm}).</p> - -<p>You can use the <code>shell</code> 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 <code>shell</code> command like this: </p> - - <pre class="no-pretty-print">adb [-d|-e|-s <serialNumber>] shell <shell_command></pre> - -<p>Or enter a remote shell on an emulator/device like this:</p> - - <pre class="no-pretty-print">adb [-d|-e|-s <serialNumber>] shell</pre> - -<p>When you are ready to exit the remote shell, press CTRL+D or type -<code>exit</code>. </p> - - - - - -<h3 id="am">Using activity manager (am)</h3> - -<p>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:</p> -<pre class="no-pretty-print"> -am <command> -</pre> - -<p>You can also issue an activity manager command directly from adb -without entering a remote shell. For example:</p> -<pre class="no-pretty-print"> -adb shell am start -a android.intent.action.VIEW -</pre> - - -<p class="table-caption"><strong>Table 2.</strong> Available activity manager commands</p> -<table> -<tr> - <th>Command</th> - <th>Description</th> -</tr> - -<tr> -<td><code> -start [options] <INTENT> -</code></td> -<td>Start an {@link android.app.Activity} specified by {@code <INTENT>}. <p>See the -<a href="#IntentSpec">Specification for <INTENT> arguments</a>. -<p>Options are: -<ul> - <li>{@code -D}: Enable debugging. - <li>{@code -W}: Wait for launch to complete. - <li>{@code --start-profiler <FILE>}: Start profiler and send results to {@code <FILE>}. - <li>{@code -P <FILE>}: Like <code>--start-profiler</code>, - but profiling stops when the app goes idle. - <li>{@code -R}: Repeat the activity launch {@code <COUNT>} times. Prior to each repeat, - the top activity will be finished. - <li>{@code -S}: Force stop the target app before starting the activity. - <li>{@code --opengl-trace}: Enable tracing of OpenGL functions. - <li>{@code --user <USER_ID> | current}: Specify which user to run as; if not - specified, then run as the current user. -</ul> -</td> -</tr> - -<tr> -<td><code> -startservice [options] <INTENT> -</code></td> -<td>Start the {@link android.app.Service} specified by {@code <INTENT>}. <p>See the -<a href="#IntentSpec">Specification for <INTENT> arguments</a>. -<p>Options are: -<ul> - <li>{@code --user <USER_ID> | current}: Specify which user to run as; if not - specified, then run as the current user. -</ul> -</td> -</tr> - -<tr> -<td><code> -force-stop <PACKAGE> -</code></td> -<td>Force stop everything associated with {@code <PACKAGE>} (the app's package name). -</td> -</tr> - -<tr> -<td><code> -kill [options] <PACKAGE> -</code></td> -<td> 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. - <p>Options are: - <ul> - <li>{@code --user <USER_ID> | all | current}: Specify user whose processes to kill; - all users if not specified. - </ul> -</td> -</tr> - -<tr> -<td><code> -kill-all -</code></td> -<td>Kill all background processes. -</td> -</tr> - -<tr> -<td><code> -broadcast [options] <INTENT> -</code></td> -<td>Issue a broadcast intent. <p>See the -<a href="#IntentSpec">Specification for <INTENT> arguments</a>. -<p>Options are: -<ul> - <li>{@code [--user <USER_ID> | all | current]}: Specify which user to send to; if not - specified then send to all users. -</ul> -</td> -</tr> - -<tr> -<td><code> -instrument [options] <COMPONENT> -</code></td> -<td>Start monitoring with an {@link android.app.Instrumentation} instance. - Typically the target {@code <COMPONENT>} - is the form {@code <TEST_PACKAGE>/<RUNNER_CLASS>}. <p>Options are: -<ul> - <li>{@code -r}: Print raw results (otherwise decode - {@code <REPORT_KEY_STREAMRESULT>}). Use with - {@code [-e perf true]} to generate raw output for performance measurements. - - <li>{@code -e <NAME> <VALUE>}: Set argument {@code <NAME>} to {@code <VALUE>}. - For test runners a common form is {@code - -e <testrunner_flag> <value>[,<value>...]}. - - <li>{@code -p <FILE>}: Write profiling data to {@code <FILE>}. - - <li>{@code -w}: Wait for instrumentation to finish before returning. Required for - test runners. - - <li>{@code --no-window-animation}: Turn off window animations while running. - <li>{@code --user <USER_ID> | current}: Specify which user instrumentation runs in; - current user if not specified. -</ul> - -</td> -</tr> - -<tr> -<td><code> -profile start <PROCESS> <FILE> -</code></td> -<td>Start profiler on {@code <PROCESS>}, write results to {@code <FILE>}. -</td> -</tr> - -<tr> -<td><code> -profile stop <PROCESS> -</code></td> -<td>Stop profiler on {@code <PROCESS>}. -</td> -</tr> - -<tr> -<td style="white-space:nowrap"><code> -dumpheap [options] <PROCESS> <FILE> -</code></td> -<td>Dump the heap of {@code <PROCESS>}, write to {@code <FILE>}. <p>Options are: -<ul> - <li>{@code --user [<USER_ID>|current]}: When supplying a process name, - specify user of process to dump; uses current user if not specified. - <li>{@code -n}: Dump native heap instead of managed heap. -</ul> -</td> -</tr> - -<tr> -<td><code> -set-debug-app [options] <PACKAGE> -</code></td> -<td>Set application {@code <PACKAGE>} to debug. <p>Options are: -<ul> - <li>{@code -w}: Wait for debugger when application starts. - <li>{@code --persistent}: Retain this value. -</ul> -</td> -</tr> - -<tr> -<td><code> -clear-debug-app -</code></td> -<td>Clear the package previous set for debugging with {@code set-debug-app}. -</td> -</tr> - -<tr> -<td><code> -monitor [options] -</code></td> -<td>Start monitoring for crashes or ANRs. <p>Options are: -<ul> - <li>{@code --gdb}: Start gdbserv on the given port at crash/ANR. -</ul> -</td> -</tr> - -<tr> -<td><code> -screen-compat [on|off] <PACKAGE> -</code></td> -<td>Control <a href="{@docRoot}guide/practices/screen-compat-mode.html">screen -compatibility</a> mode of {@code <PACKAGE>}.</p> -</td> -</tr> - -<tr> -<td><code> -display-size [reset|<WxH>] -</code></td> -<td>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. -<p>Example:<br><code>am display-size 1280x800</code> -</td> -</tr> - -<tr> -<td><code> -display-density <dpi> -</code></td> -<td>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. -<p>Example:<br><code>am display-density 480</code> -</td> -</tr> - -<tr> -<td><code> -to-uri <INTENT> -</code></td> -<td>Print the given intent specification as a URI. <p>See the -<a href="#IntentSpec">Specification for <INTENT> arguments</a>. -</td> -</tr> - -<tr> -<td><code> -to-intent-uri <INTENT> -</code></td> -<td>Print the given intent specification as an {@code intent:} URI. <p>See the -<a href="#IntentSpec">Specification for <INTENT> arguments</a>. -</td> -</tr> -</table> - - - - - -<h4 id="IntentSpec"> - <a href="" class="expandable" onclick="toggleExpandable(this,'.intents'); -return false">Specification for <INTENT> arguments</a></h4> - -<div class="intents" style="display:none"> - -<p>For activity manager commands that take a {@code <INTENT>} argument, you can -specify the intent with the following options:</p> - -<dl> - <dt>{@code -a <ACTION>}</dt> - <dd>Specify the intent action, such as "android.intent.action.VIEW". - You can declare this only once. - - <dt>{@code -d <DATA_URI>}</dt> - <dd>Specify the intent data URI, such as "content://contacts/people/1". - You can declare this only once. - - <dt>{@code -t <MIME_TYPE>}</dt> - <dd>Specify the intent MIME type, such as "image/png". - You can declare this only once. - - <dt>{@code -c <CATEGORY>}</dt> - <dd>Specify an intent category, such as "android.intent.category.APP_CONTACTS". - - <dt>{@code -n <COMPONENT>}</dt> - <dd>Specify the component name with package name prefix to create an explicit intent, such - as "com.example.app/.ExampleActivity". - - <dt>{@code -f <FLAGS>}</dt> - <dd>Add flags to the intent, as supported by {@link - android.content.Intent#setFlags setFlags()}. - - <dt>{@code --esn <EXTRA_KEY>}</dt> - <dd>Add a null extra. This option is not supported for URI intents. - - <dt>{@code -e|--es <EXTRA_KEY> <EXTRA_STRING_VALUE>}</dt> - <dd>Add string data as a key-value pair. - - <dt>{@code --ez <EXTRA_KEY> <EXTRA_BOOLEAN_VALUE>}</dt> - <dd>Add boolean data as a key-value pair. - - <dt>{@code --ei <EXTRA_KEY> <EXTRA_INT_VALUE>}</dt> - <dd>Add integer data as a key-value pair. - - <dt>{@code --el <EXTRA_KEY> <EXTRA_LONG_VALUE>}</dt> - <dd>Add long data as a key-value pair. - - <dt>{@code --ef <EXTRA_KEY> <EXTRA_FLOAT_VALUE>}</dt> - <dd>Add float data as a key-value pair. - - <dt>{@code --eu <EXTRA_KEY> <EXTRA_URI_VALUE>}</dt> - <dd>Add URI data as a key-value pair. - - <dt>{@code --ecn <EXTRA_KEY> <EXTRA_COMPONENT_NAME_VALUE>}</dt> - <dd>Add a component name, which is converted and passed as - a {@link android.content.ComponentName} object. - - <dt>{@code --eia <EXTRA_KEY> <EXTRA_INT_VALUE>[,<EXTRA_INT_VALUE...]}</dt> - <dd>Add an array of integers. - - <dt>{@code --ela <EXTRA_KEY> <EXTRA_LONG_VALUE>[,<EXTRA_LONG_VALUE...]}</dt> - <dd>Add an array of longs. - - <dt>{@code --efa <EXTRA_KEY> <EXTRA_FLOAT_VALUE>[,<EXTRA_FLOAT_VALUE...]}</dt> - <dd>Add an array of floats. - - <dt>{@code --grant-read-uri-permission}</dt> - <dd>Include the flag {@link android.content.Intent#FLAG_GRANT_READ_URI_PERMISSION}. - - <dt>{@code --grant-write-uri-permission}</dt> - <dd>Include the flag {@link android.content.Intent#FLAG_GRANT_WRITE_URI_PERMISSION}. - - <dt>{@code --debug-log-resolution}</dt> - <dd>Include the flag {@link android.content.Intent#FLAG_DEBUG_LOG_RESOLUTION}. - - <dt>{@code --exclude-stopped-packages}</dt> - <dd>Include the flag {@link android.content.Intent#FLAG_EXCLUDE_STOPPED_PACKAGES}. - - <dt>{@code --include-stopped-packages}</dt> - <dd>Include the flag {@link android.content.Intent#FLAG_INCLUDE_STOPPED_PACKAGES}. - - <dt>{@code --activity-brought-to-front}</dt> - <dd>Include the flag {@link android.content.Intent#FLAG_ACTIVITY_BROUGHT_TO_FRONT}. - - <dt>{@code --activity-clear-top}</dt> - <dd>Include the flag {@link android.content.Intent#FLAG_ACTIVITY_CLEAR_TOP}. - - <dt>{@code --activity-clear-when-task-reset}</dt> - <dd>Include the flag {@link android.content.Intent#FLAG_ACTIVITY_CLEAR_WHEN_TASK_RESET}. - - <dt>{@code --activity-exclude-from-recents}</dt> - <dd>Include the flag {@link android.content.Intent#FLAG_ACTIVITY_EXCLUDE_FROM_RECENTS}. - - <dt>{@code --activity-launched-from-history}</dt> - <dd>Include the flag {@link android.content.Intent#FLAG_ACTIVITY_LAUNCHED_FROM_HISTORY}. - - <dt>{@code --activity-multiple-task}</dt> - <dd>Include the flag {@link android.content.Intent#FLAG_ACTIVITY_MULTIPLE_TASK}. - - <dt>{@code --activity-no-animation}</dt> - <dd>Include the flag {@link android.content.Intent#FLAG_ACTIVITY_NO_ANIMATION}. - - <dt>{@code --activity-no-history}</dt> - <dd>Include the flag {@link android.content.Intent#FLAG_ACTIVITY_NO_HISTORY}. - - <dt>{@code --activity-no-user-action}</dt> - <dd>Include the flag {@link android.content.Intent#FLAG_ACTIVITY_NO_USER_ACTION}. - - <dt>{@code --activity-previous-is-top}</dt> - <dd>Include the flag {@link android.content.Intent#FLAG_ACTIVITY_PREVIOUS_IS_TOP}. - - <dt>{@code --activity-reorder-to-front}</dt> - <dd>Include the flag {@link android.content.Intent#FLAG_ACTIVITY_REORDER_TO_FRONT}. - - <dt>{@code --activity-reset-task-if-needed}</dt> - <dd>Include the flag {@link android.content.Intent#FLAG_ACTIVITY_RESET_TASK_IF_NEEDED}. - - <dt>{@code --activity-single-top}</dt> - <dd>Include the flag {@link android.content.Intent#FLAG_ACTIVITY_SINGLE_TOP}. - - <dt>{@code --activity-clear-task}</dt> - <dd>Include the flag {@link android.content.Intent#FLAG_ACTIVITY_CLEAR_TASK}. - - <dt>{@code --activity-task-on-home}</dt> - <dd>Include the flag {@link android.content.Intent#FLAG_ACTIVITY_TASK_ON_HOME}. - - <dt>{@code --receiver-registered-only}</dt> - <dd>Include the flag {@link android.content.Intent#FLAG_RECEIVER_REGISTERED_ONLY}. - - <dt>{@code --receiver-replace-pending}</dt> - <dd>Include the flag {@link android.content.Intent#FLAG_RECEIVER_REPLACE_PENDING}. - - <dt>{@code --selector}</dt> - <dd>Requires the use of {@code -d} and {@code -t} options to set the intent data and type. - - <dt>{@code <URI> <COMPONENT> <PACKAGE>}</dt> - <dd>You can directly specify a URI, package name, and component name when not qualified - by one of the above options. When an argument is unqualified, the tool assumes the argument - is a URI if it contains a ":" (colon); it assumes the argument is a component name if it - contains a "/" (forward-slash); otherwise it assumes the argument is a package name. - -</dl> -</div><!-- end 'intents' --> -<script> - $(window).hashchange( function(){ - if ((location.hash == "#IntentSpec") && !($("#IntentSpec a").hasClass("expanded"))) { - $("#IntentSpec a").click(); - } - }); -</script> - - - -<h3 id="pm">Using package manager (pm)</h3> - -<p>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:</p> -<pre class="no-pretty-print"> -pm <command> -</pre> - -<p>You can also issue a package manager command directly from adb -without entering a remote shell. For example:</p> -<pre class="no-pretty-print"> -adb shell pm uninstall com.example.MyApp -</pre> - -<p class="table-caption"><strong>Table 3.</strong> Available package manager commands.</p> -<table> -<tr> - <th>Command</th> - <th>Description</th> -</tr> - -<tr> -<td><code> -list packages [options] <FILTER> -</code></td> -<td>Prints all packages, optionally only - those whose package name contains the text in {@code <FILTER>}. <p>Options: -<ul> - <li>{@code -f}: See their associated file. - <li>{@code -d}: Filter to only show disabled packages. - <li>{@code -e}: Filter to only show enabled packages. - <li>{@code -s}: Filter to only show system packages. - <li>{@code -3}: Filter to only show third party packages. - <li>{@code -i}: See the installer for the packages. - <li>{@code -u}: Also include uninstalled packages. - <li>{@code --user <USER_ID>}: The user space to query. -</ul> -</td> -</tr> - -<tr> -<td><code> -list permission-groups -</code></td> -<td>Prints all known permission groups. -</td> -</tr> - -<tr> -<td><code> -list permissions [options] <GROUP> -</code></td> -<td>Prints all known permissions, optionally only - those in {@code <GROUP>}. <p>Options: -<ul> - <li>{@code -g}: Organize by group. - <li>{@code -f}: Print all information. - <li>{@code -s}: Short summary. - <li>{@code -d}: Only list dangerous permissions. - <li>{@code -u}: List only the permissions users will see. -</ul> -</td> -</tr> - -<tr> -<td><code> -list instrumentation -</code></td> -<td>List all test packages. <p>Options: - <ul> - <li>{@code -f}: List the APK file for the test package. - <li>{@code <TARGET_PACKAGE>}: List test packages for only this app. - </ul> -</td> -</tr> - -<tr> -<td><code> -list features -</code></td> -<td>Prints all features of the system. -</td> -</tr> - -<tr> -<td><code> -list libraries -</code></td> -<td>Prints all the libraries supported by the current device. -</td> -</tr> - -<tr> -<td><code> -list users -</code></td> -<td>Prints all users on the system. -</td> -</tr> - -<tr> -<td><code> -path <PACKAGE> -</code></td> -<td>Print the path to the APK of the given {@code <PACKAGE>}. -</td> -</tr> - -<tr> -<td><code> -install [options] <PATH> -</code></td> -<td>Installs a package (specified by {@code <PATH>}) to the system. <p>Options: - <ul> - <li>{@code -r}: Reinstall an exisiting app, keeping its data. - <li>{@code -t}: Allow test APKs to be installed. - <li>{@code -i <INSTALLER_PACKAGE_NAME>}: Specify the installer package name. - <li>{@code -s}: Install package on the shared mass storage (such as sdcard). - <li>{@code -f}: Install package on the internal system memory. - <li>{@code -d}: Allow version code downgrade. - </ul> -</td> -</tr> - -<tr> -<td><code> -uninstall [options] <PACKAGE> -</code></td> -<td>Removes a package from the system. <p>Options: - <ul> - <li>{@code -k}: Keep the data and cache directories around after package removal. - </ul> -</td> -</tr> - -<tr> -<td><code> -clear <PACKAGE> -</code></td> -<td>Deletes all data associated with a package. -</td> -</tr> - -<tr> -<td><code> -enable <PACKAGE_OR_COMPONENT> -</code></td> -<td>Enable the given package or component (written as "package/class"). -</td> -</tr> - -<tr> -<td><code> -disable <PACKAGE_OR_COMPONENT> -</code></td> -<td>Disable the given package or component (written as "package/class"). -</td> -</tr> - -<tr> -<td style="white-space:nowrap"><code> -disable-user [options] <PACKAGE_OR_COMPONENT> -</code></td> -<td><p>Options: - <ul> - <li>{@code --user <USER_ID>}: The user to disable. - </ul> -</td> -</tr> - -<tr> -<td><code> -grant <PACKAGE_PERMISSION> -</code></td> -<td>Grant permissions - to applications. Only optional permissions the application has - declared can be granted. -</td> -</tr> - -<tr> -<td><code> -revoke <PACKAGE_PERMISSION> -</code></td> -<td>Revoke permissions - to applications. Only optional permissions the application has - declared can be revoked. -</td> -</tr> - -<tr> -<td><code> -set-install-location <LOCATION> -</code></td> -<td>Changes the default install location. Location values: -<ul> - <li>{@code 0}: Auto—Let system decide the best location. - <li>{@code 1}: Internal—install on internal device storage. - <li>{@code 2}: External—install on external media. -</ul> -<p class="note"><strong>Note:</strong> This is only intended for debugging; using this can cause - applications to break and other undesireable behavior.</p> -</td> -</tr> - -<tr> -<td><code> -get-install-location -</code></td> -<td>Returns the current install location. Return values: -<ul> - <li>{@code 0 [auto]}: Lets system decide the best location - <li>{@code 1 [internal]}: Installs on internal device storage - <li>{@code 2 [external]}: Installs on external media -</ul> -</td> -</tr> - -<tr> -<td><code> -set-permission-enforced <PERMISSION> [true|false] -</code></td> -<td>Specifies whether the given permission should be enforced. -</td> -</tr> - -<tr> -<td><code> -trim-caches <DESIRED_FREE_SPACE> -</code></td> -<td>Trim cache files to reach the given free space. -</td> -</tr> - -<tr> -<td><code> -create-user <USER_NAME> -</code></td> -<td>Create a new user with the given {@code <USER_NAME>}, - printing the new user identifier of the user. -</td> -</tr> - -<tr> -<td><code> -remove-user <USER_ID> -</code></td> -<td>Remove the user with the given {@code <USER_IDENTIFIER>}, - deleting all data associated with that user -</td> -</tr> - -<tr> -<td><code> -get-max-users -</code></td> -<td>Prints the maximum number of users supported by the device. -</td> -</tr> - -</table> - - - - - - - -<h3 id="sqlite">Examining sqlite3 databases from a remote shell</h3> - -<p>From an adb remote shell, you can use the -<a href="http://www.sqlite.org/sqlite.html">sqlite3</a> command-line program to -manage SQLite databases created by Android applications. The -<code>sqlite3</code> tool includes many useful commands, such as -<code>.dump</code> to print out the contents of a table and -<code>.schema</code> to print the SQL CREATE statement for an existing table. -The tool also gives you the ability to execute SQLite commands on the fly.</p> - -<p>To use <code>sqlite3</code>, enter a remote shell on the emulator instance, as described above, -then invoke the tool using the <code>sqlite3</code> command. Optionally, when invoking -<code>sqlite3</code> you can specify the full path to the database you want to explore. -Emulator/device instances store SQLite3 databases in the folder -<code><span chatdir="1"><span chatindex="259474B4B070F261">/data/data/<em><package_name></em>/databases</span></span>/</code>. </p> - -<p>Here's an example: </p> - -<pre class="no-pretty-print">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 -<em>.... enter commands, then quit...</em> -sqlite> .exit </pre> - -<p>Once you've invoked <code>sqlite3</code>, you can issue <code>sqlite3</code> commands in the -shell. To exit and return to the adb remote shell, use <code>exit</code> or <code>CTRL+D</code>. - - - - -<h3 id="screenrecord">Recording a device screen</h3> - -<p>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, which you can then download and use as part of a video presentation. This utility is useful - for developers who want to create promotional or training videos without using a separate - recording device.</p> - -<p>To use the {@code screenrecord} from the command line, type the following: - -<pre> -$ adb shell screenrecord /sdcard/demo.mp4 -</pre> - -<p>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}.</p> - -<p>Here's an example recording session, using the adb shell to record the video and the -{@code pull} command to download the file from the device:<p> - -<pre> -$ adb shell -shell@ $ screenrecord --verbose /sdcard/demo.mp4 -(press Ctrl-C to stop) -shell@ $ exit -$ adb pull /sdcard/demo.mp4 -</pre> - -<p>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.</p> - -<p>There are some known limitations of the {@code screenrecord} utility that you should be aware - of when using it:</p> - -<ul> - <li>Some devices may not be able to record at their native display resolution. - If you encounter problems with screen recording, try using a lower screen resolution.</li> - <li>Rotation of the screen during recording is not supported. If the screen does rotate during - recording, some of the screen is cut off in the recording.</li> - <li>Audio is not recorded with the video file.</li> -</ul> - - -<p class="table-caption"><strong>Table 4.</strong> {@code screenrecord} options</p> - -<table> - <tr> - <th>Options</th> - <th>Description</th> - </tr> - - <tr> - <td><code>--help</code> - </td> - <td>Displays a usage summary.</td> - </tr> - - <tr> - <td style="white-space:nowrap"> - <code>--size <WIDTHxHEIGHT></code> - </td> - <td>Sets the video size, for example: {@code 1280x720}. The default value is the device's main - display resolution (if supported), 1280x720 if not. For best results, use a size supported - by your device's Advanced Video Coding (AVC) encoder.</td> - </tr> - - <tr> - <td><code>--bit-rate <RATE></code></td> - <td>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 or lower it for smaller movie - files. The following example sets the recording bit rate to 6Mbps: - <pre>screenrecord --bit-rate 6000000 /sdcard/demo.mp4</pre> - </td> - </tr> - - <tr> - <td><code>--time-limit <TIME></code></td> - <td>Sets the maximum recording time, in seconds. The default and maximum value is 180 - (3 minutes).</td> - </tr> - - <tr> - <td><code>--rotate</code></td> - <td>Rotates the output 90 degrees. This feature is experimental.</td> - </tr> - - <tr> - <td><code>--verbose</code></td> - <td>Displays log information on command line screen. If you do not set this option, - the utility does not display any information while running.</td> - </tr> - -</table> - - - - -<h3 id="monkey">UI/Application Exerciser Monkey</h3> - -<p>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.</p> - -<p>The simplest way to use the monkey is with the following command, which launches your -application and sends 500 pseudo-random events to it.</p> - -<pre class="no-pretty-print">adb shell monkey -v -p your.package.name 500</pre> - -<p>For more information about command options for Monkey, see the complete -<a href="{@docRoot}tools/help/monkey.html" title="monkey">UI/Application Exerciser Monkey</a> documentation page.</p> - - - - - -<h3 id="othershellcommands">Other shell commands</h3> - -<p>For a list of all the available shell programs, use the following command:</p> - -<pre class="no-pretty-print">adb shell ls /system/bin</pre> - -<p>Help is available for most of the commands. </p> - -<p>Table 5 lists some of the more common adb shell commands.</p> - -<p class="table-caption"><strong>Table 5.</strong> Some other adb shell commands</p> -<table> -<tr> - <th>Shell Command</th> - <th>Description</th> - <th>Comments</th> -</tr> - -<tr> -<td><code>dumpsys</code></td> -<td>Dumps system data to the screen.</td> -<td rowspan=4">The <a href="{@docRoot}tools/debugging/ddms.html">Dalvik Debug Monitor Server</a> -(DDMS) tool offers integrated debug environment that you may find easier to use.</td> -</tr> - -<tr> -<td><code>dumpstate</code></td> -<td>Dumps state to a file.</td> -</tr> - -<tr> -<td><code>logcat [option]... [filter-spec]...</code></td> -<td>Enables system and app logging and prints output to the screen. </td> -</tr> - -<tr> -<td><code>dmesg</code></td> -<td>Prints kernel debugging messages to the screen. </td> -</tr> - -<tr> -<td><code>start</code></td> -<td>Starts (restarts) an emulator/device instance.</td> -<td> </td> -</tr> - -<tr> -<td><code>stop</code></td> -<td>Stops execution of an emulator/device instance.</td> -<td> </td> -</tr> - -</table> - - - - - - - -<a name="stdout"></a> -<a name="usinglogcat"></a> -<a name="outputformat"></a> -<a name="filteringoutput"></a> -<a name="stdout"></a> -<a name="logcatoptions"></a> - -<h2 id="logcat">Enabling logcat logging</h2> - -<p>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 <code>logcat</code> command.</p> - -<p>You can use the <code>logcat</code> command to view and follow the contents of the system's log buffers. The general usage is:</p> - -<pre class="no-pretty-print">[adb] logcat [option] ... [filter-spec] ...</pre> - -<p>You can use the <code>logcat</code> 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</p> - -<pre class="no-pretty-print">adb logcat</pre> - -<p>and from a remote adb shell you use</p> - -<pre class="no-pretty-print">logcat</pre> - -<p>See <a href="{@docRoot}tools/debugging/debugging-log.html">Reading and Writing Logs</a> for complete information about logcat commend options and filter specifications.</p> - - - - - -<h2 id="stopping">Stopping the adb server</h2> - -<p>In some cases, you might need to terminate the adb server process and then restart it. For example, if adb does not respond to a command, you can terminate the server and restart it and that may resolve the problem. </p> +<p>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).</p> <p>To stop the adb server, use the <code>kill-server</code> command. You can then restart the server by issuing any other adb command. </p> @@ -1457,4 +506,4 @@ adb kill-server and then start over from the beginning. </li> -</ol> +</ol>
\ No newline at end of file diff --git a/docs/html/tools/help/adt.jd b/docs/html/tools/help/adt.jd index 8abe1b4..0fac62d 100644 --- a/docs/html/tools/help/adt.jd +++ b/docs/html/tools/help/adt.jd @@ -30,20 +30,21 @@ page.tags=adt </div> </div> - <p>ADT (Android Developer Tools) is a plugin for Eclipse that provides a suite of +<p class="caution"> + <strong>Important:</strong> Support for the Android Developer Tools (ADT) in Eclipse is ending, + per our <a href= + "http://android-developers.blogspot.com/2015/06/an-update-on-eclipse-android-developer.html" + class="external-link">announcement</a>. You should migrate your app development projects to + Android Studio as soon as possible. For more information on transitioning to Android Studio, see + <a href="{@docRoot}sdk/installing/migrate.html">Migrating to Android Studio</a>. +</p> + + <p>Android Developer Tools (ADT) is a plugin for Eclipse that provides a suite of tools that are integrated with the Eclipse IDE. It offers you access to many features that help you develop Android applications. ADT provides GUI access to many of the command line SDK tools as well as a UI design tool for rapid prototyping, designing, and building of your application's user interface.</p> -<p class="note"><strong>Note:</strong> -If you have been using Eclipse with ADT, be aware that <a -href="{@docRoot}tools/studio/index.html">Android Studio</a> 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 <a href="/sdk/installing/migrate.html">Migrating to Android -Studio</a>.</p> - <p>If you still wish to use the ADT plugin for Eclipse, see <a href="{@docRoot}sdk/installing/installing-adt.html">Installing Eclipse Plugin.</a> </p> diff --git a/docs/html/tools/help/index.jd b/docs/html/tools/help/index.jd index 4c97d0c..f90d029 100644 --- a/docs/html/tools/help/index.jd +++ b/docs/html/tools/help/index.jd @@ -68,7 +68,10 @@ avd</code>) the emulator (<code>emulator</code>), and the Dalvik Debug Monitor S <dt><a href="{@docRoot}tools/help/adb.html">adb</a></dt> <dd>Android Debug Bridge (adb) is a versatile command line tool that lets you communicate with an emulator instance or connected Android-powered device. It also provides access to the - device shell for advanced command-line operations.</dd> + device shell.</dd> + + <dt><a href="{@docRoot}tools/help/shell.html">ADB Shell Commands</a></dt> + <dd>Learn the commands available for advanced command-line operations.</dd> <dt><a href="{@docRoot}tools/debugging/ddms.html">Dalvik Debug Monitor Server (ddms)</a></dt> @@ -109,11 +112,9 @@ you can view the file in a profiling tool of your choice.</dd> <dt><a href="{@docRoot}tools/help/jobb.html">JOBB</a></dt> <dd>Allows you to build encrypted and unencrypted - <a href="{@docRoot}{@docRoot}google/play/expansion-files.html">APK expansion files</a> in Opaque + <a href="{@docRoot}google/play/expansion-files.html">APK expansion files</a> in Opaque Binary Blob (OBB) format.</dd> -<a href="{@docRoot}{@docRoot}google/play/expansion-files.html">APK expansion files</a> - <dt><a href="{@docRoot}tools/help/proguard.html">ProGuard</a></dt> <dd>Shrinks, optimizes, and obfuscates your code by removing unused code and renaming classes, fields, and methods with semantically obscure names.</dd> diff --git a/docs/html/tools/help/shell.jd b/docs/html/tools/help/shell.jd new file mode 100644 index 0000000..417c871 --- /dev/null +++ b/docs/html/tools/help/shell.jd @@ -0,0 +1,898 @@ +page.title=ADB Shell Commands +parent.title=Tools +parent.link=index.html +page.tags=shell,adb,am,pm,screenrecord,screencap +@jd:body + +<div id="qv-wrapper"> +<div id="qv"> + <h2>In this document</h2> +<ol> + <li><a href="#shellcommands">Issuing Shell Commands</a> + <li><a href="#am">Using activity manager (am)</a></li> + <li><a href="#pm">Using package manager (pm)</a></li> + <li><a href="#screencap">Taking a device screenshot</a></li> + <li><a href="#screenrecord">Recording a device screen</a></li> + <li><a href="#othershellcommands">Other shell commands</a></li> + </li> +</ol> + +</div> +</div> + +<p>The <a href="{@docRoot}tools/help/adb.html">Android Debug Bridge</a> (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 <code>/system/bin/...</code> +</p> + +<h2 id="shellcommands">Issuing Shell Commands</h2> + +<p>You can use the <code>shell</code> 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 <code>shell</code> command like this: </p> + + <pre class="no-pretty-print">adb [-d|-e|-s <serialNumber>] shell <shell_command></pre> + +<p>Or enter a remote shell on an emulator/device like this:</p> + + <pre class="no-pretty-print">adb [-d|-e|-s <serialNumber>] shell</pre> + +<p>When you are ready to exit the remote shell, press CTRL+D or type +<code>exit</code>. </p> + + + + + +<h2 id="am">Using activity manager (am)</h2> + +<p>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:</p> +<pre class="no-pretty-print"> +am <command> +</pre> + +<p>You can also issue an activity manager command directly from adb +without entering a remote shell. For example:</p> +<pre class="no-pretty-print"> +adb shell am start -a android.intent.action.VIEW +</pre> + + +<p class="table-caption"><strong>Table 2.</strong> Available activity manager commands</p> +<table> +<tr> + <th>Command</th> + <th>Description</th> +</tr> + +<tr> +<td><code> +start [options] <INTENT> +</code></td> +<td>Start an {@link android.app.Activity} specified by {@code <INTENT>}. <p>See the +<a href="#IntentSpec">Specification for <INTENT> arguments</a>. +<p>Options are: +<ul> + <li>{@code -D}: Enable debugging. + <li>{@code -W}: Wait for launch to complete. + <li>{@code --start-profiler <FILE>}: Start profiler and send results to {@code <FILE>}. + <li>{@code -P <FILE>}: Like <code>--start-profiler</code>, + but profiling stops when the app goes idle. + <li>{@code -R}: Repeat the activity launch {@code <COUNT>} times. Prior to each repeat, + the top activity will be finished. + <li>{@code -S}: Force stop the target app before starting the activity. + <li>{@code --opengl-trace}: Enable tracing of OpenGL functions. + <li>{@code --user <USER_ID> | current}: Specify which user to run as; if not + specified, then run as the current user. +</ul> +</td> +</tr> + +<tr> +<td><code> +startservice [options] <INTENT> +</code></td> +<td>Start the {@link android.app.Service} specified by {@code <INTENT>}. <p>See the +<a href="#IntentSpec">Specification for <INTENT> arguments</a>. +<p>Options are: +<ul> + <li>{@code --user <USER_ID> | current}: Specify which user to run as; if not + specified, then run as the current user. +</ul> +</td> +</tr> + +<tr> +<td><code> +force-stop <PACKAGE> +</code></td> +<td>Force stop everything associated with {@code <PACKAGE>} (the app's package name). +</td> +</tr> + +<tr> +<td><code> +kill [options] <PACKAGE> +</code></td> +<td> 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. + <p>Options are: + <ul> + <li>{@code --user <USER_ID> | all | current}: Specify user whose processes to kill; + all users if not specified. + </ul> +</td> +</tr> + +<tr> +<td><code> +kill-all +</code></td> +<td>Kill all background processes. +</td> +</tr> + +<tr> +<td><code> +broadcast [options] <INTENT> +</code></td> +<td>Issue a broadcast intent. <p>See the +<a href="#IntentSpec">Specification for <INTENT> arguments</a>. +<p>Options are: +<ul> + <li>{@code [--user <USER_ID> | all | current]}: Specify which user to send to; if not + specified then send to all users. +</ul> +</td> +</tr> + +<tr> +<td><code> +instrument [options] <COMPONENT> +</code></td> +<td>Start monitoring with an {@link android.app.Instrumentation} instance. + Typically the target {@code <COMPONENT>} + is the form {@code <TEST_PACKAGE>/<RUNNER_CLASS>}. <p>Options are: +<ul> + <li>{@code -r}: Print raw results (otherwise decode + {@code <REPORT_KEY_STREAMRESULT>}). Use with + {@code [-e perf true]} to generate raw output for performance measurements. + + <li>{@code -e <NAME> <VALUE>}: Set argument {@code <NAME>} to {@code <VALUE>}. + For test runners a common form is {@code + -e <testrunner_flag> <value>[,<value>...]}. + + <li>{@code -p <FILE>}: Write profiling data to {@code <FILE>}. + + <li>{@code -w}: Wait for instrumentation to finish before returning. Required for + test runners. + + <li>{@code --no-window-animation}: Turn off window animations while running. + <li>{@code --user <USER_ID> | current}: Specify which user instrumentation runs in; + current user if not specified. +</ul> + +</td> +</tr> + +<tr> +<td><code> +profile start <PROCESS> <FILE> +</code></td> +<td>Start profiler on {@code <PROCESS>}, write results to {@code <FILE>}. +</td> +</tr> + +<tr> +<td><code> +profile stop <PROCESS> +</code></td> +<td>Stop profiler on {@code <PROCESS>}. +</td> +</tr> + +<tr> +<td style="white-space:nowrap"><code> +dumpheap [options] <PROCESS> <FILE> +</code></td> +<td>Dump the heap of {@code <PROCESS>}, write to {@code <FILE>}. <p>Options are: +<ul> + <li>{@code --user [<USER_ID>|current]}: When supplying a process name, + specify user of process to dump; uses current user if not specified. + <li>{@code -n}: Dump native heap instead of managed heap. +</ul> +</td> +</tr> + +<tr> +<td><code> +set-debug-app [options] <PACKAGE> +</code></td> +<td>Set application {@code <PACKAGE>} to debug. <p>Options are: +<ul> + <li>{@code -w}: Wait for debugger when application starts. + <li>{@code --persistent}: Retain this value. +</ul> +</td> +</tr> + +<tr> +<td><code> +clear-debug-app +</code></td> +<td>Clear the package previous set for debugging with {@code set-debug-app}. +</td> +</tr> + +<tr> +<td><code> +monitor [options] +</code></td> +<td>Start monitoring for crashes or ANRs. <p>Options are: +<ul> + <li>{@code --gdb}: Start gdbserv on the given port at crash/ANR. +</ul> +</td> +</tr> + +<tr> +<td><code> +screen-compat [on|off] <PACKAGE> +</code></td> +<td>Control <a href="{@docRoot}guide/practices/screen-compat-mode.html">screen +compatibility</a> mode of {@code <PACKAGE>}.</p> +</td> +</tr> + +<tr> +<td><code> +display-size [reset|<WxH>] +</code></td> +<td>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. +<p>Example:<br><code>am display-size 1280x800</code> +</td> +</tr> + +<tr> +<td><code> +display-density <dpi> +</code></td> +<td>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. +<p>Example:<br><code>am display-density 480</code> +</td> +</tr> + +<tr> +<td><code> +to-uri <INTENT> +</code></td> +<td>Print the given intent specification as a URI. <p>See the +<a href="#IntentSpec">Specification for <INTENT> arguments</a>. +</td> +</tr> + +<tr> +<td><code> +to-intent-uri <INTENT> +</code></td> +<td>Print the given intent specification as an {@code intent:} URI. <p>See the +<a href="#IntentSpec">Specification for <INTENT> arguments</a>. +</td> +</tr> +</table> + + + + + +<h3 id="IntentSpec"> + <a href="" class="expandable" onclick="toggleExpandable(this,'.intents'); +return false">Specification for <INTENT> arguments</a></h3> + +<div class="intents" style="display:none"> + +<p>For activity manager commands that take a {@code <INTENT>} argument, you can +specify the intent with the following options:</p> + +<dl> + <dt>{@code -a <ACTION>}</dt> + <dd>Specify the intent action, such as "android.intent.action.VIEW". + You can declare this only once. + + <dt>{@code -d <DATA_URI>}</dt> + <dd>Specify the intent data URI, such as "content://contacts/people/1". + You can declare this only once. + + <dt>{@code -t <MIME_TYPE>}</dt> + <dd>Specify the intent MIME type, such as "image/png". + You can declare this only once. + + <dt>{@code -c <CATEGORY>}</dt> + <dd>Specify an intent category, such as "android.intent.category.APP_CONTACTS". + + <dt>{@code -n <COMPONENT>}</dt> + <dd>Specify the component name with package name prefix to create an explicit intent, such + as "com.example.app/.ExampleActivity". + + <dt>{@code -f <FLAGS>}</dt> + <dd>Add flags to the intent, as supported by {@link + android.content.Intent#setFlags setFlags()}. + + <dt>{@code --esn <EXTRA_KEY>}</dt> + <dd>Add a null extra. This option is not supported for URI intents. + + <dt>{@code -e|--es <EXTRA_KEY> <EXTRA_STRING_VALUE>}</dt> + <dd>Add string data as a key-value pair. + + <dt>{@code --ez <EXTRA_KEY> <EXTRA_BOOLEAN_VALUE>}</dt> + <dd>Add boolean data as a key-value pair. + + <dt>{@code --ei <EXTRA_KEY> <EXTRA_INT_VALUE>}</dt> + <dd>Add integer data as a key-value pair. + + <dt>{@code --el <EXTRA_KEY> <EXTRA_LONG_VALUE>}</dt> + <dd>Add long data as a key-value pair. + + <dt>{@code --ef <EXTRA_KEY> <EXTRA_FLOAT_VALUE>}</dt> + <dd>Add float data as a key-value pair. + + <dt>{@code --eu <EXTRA_KEY> <EXTRA_URI_VALUE>}</dt> + <dd>Add URI data as a key-value pair. + + <dt>{@code --ecn <EXTRA_KEY> <EXTRA_COMPONENT_NAME_VALUE>}</dt> + <dd>Add a component name, which is converted and passed as + a {@link android.content.ComponentName} object. + + <dt>{@code --eia <EXTRA_KEY> <EXTRA_INT_VALUE>[,<EXTRA_INT_VALUE...]}</dt> + <dd>Add an array of integers. + + <dt>{@code --ela <EXTRA_KEY> <EXTRA_LONG_VALUE>[,<EXTRA_LONG_VALUE...]}</dt> + <dd>Add an array of longs. + + <dt>{@code --efa <EXTRA_KEY> <EXTRA_FLOAT_VALUE>[,<EXTRA_FLOAT_VALUE...]}</dt> + <dd>Add an array of floats. + + <dt>{@code --grant-read-uri-permission}</dt> + <dd>Include the flag {@link android.content.Intent#FLAG_GRANT_READ_URI_PERMISSION}. + + <dt>{@code --grant-write-uri-permission}</dt> + <dd>Include the flag {@link android.content.Intent#FLAG_GRANT_WRITE_URI_PERMISSION}. + + <dt>{@code --debug-log-resolution}</dt> + <dd>Include the flag {@link android.content.Intent#FLAG_DEBUG_LOG_RESOLUTION}. + + <dt>{@code --exclude-stopped-packages}</dt> + <dd>Include the flag {@link android.content.Intent#FLAG_EXCLUDE_STOPPED_PACKAGES}. + + <dt>{@code --include-stopped-packages}</dt> + <dd>Include the flag {@link android.content.Intent#FLAG_INCLUDE_STOPPED_PACKAGES}. + + <dt>{@code --activity-brought-to-front}</dt> + <dd>Include the flag {@link android.content.Intent#FLAG_ACTIVITY_BROUGHT_TO_FRONT}. + + <dt>{@code --activity-clear-top}</dt> + <dd>Include the flag {@link android.content.Intent#FLAG_ACTIVITY_CLEAR_TOP}. + + <dt>{@code --activity-clear-when-task-reset}</dt> + <dd>Include the flag {@link android.content.Intent#FLAG_ACTIVITY_CLEAR_WHEN_TASK_RESET}. + + <dt>{@code --activity-exclude-from-recents}</dt> + <dd>Include the flag {@link android.content.Intent#FLAG_ACTIVITY_EXCLUDE_FROM_RECENTS}. + + <dt>{@code --activity-launched-from-history}</dt> + <dd>Include the flag {@link android.content.Intent#FLAG_ACTIVITY_LAUNCHED_FROM_HISTORY}. + + <dt>{@code --activity-multiple-task}</dt> + <dd>Include the flag {@link android.content.Intent#FLAG_ACTIVITY_MULTIPLE_TASK}. + + <dt>{@code --activity-no-animation}</dt> + <dd>Include the flag {@link android.content.Intent#FLAG_ACTIVITY_NO_ANIMATION}. + + <dt>{@code --activity-no-history}</dt> + <dd>Include the flag {@link android.content.Intent#FLAG_ACTIVITY_NO_HISTORY}. + + <dt>{@code --activity-no-user-action}</dt> + <dd>Include the flag {@link android.content.Intent#FLAG_ACTIVITY_NO_USER_ACTION}. + + <dt>{@code --activity-previous-is-top}</dt> + <dd>Include the flag {@link android.content.Intent#FLAG_ACTIVITY_PREVIOUS_IS_TOP}. + + <dt>{@code --activity-reorder-to-front}</dt> + <dd>Include the flag {@link android.content.Intent#FLAG_ACTIVITY_REORDER_TO_FRONT}. + + <dt>{@code --activity-reset-task-if-needed}</dt> + <dd>Include the flag {@link android.content.Intent#FLAG_ACTIVITY_RESET_TASK_IF_NEEDED}. + + <dt>{@code --activity-single-top}</dt> + <dd>Include the flag {@link android.content.Intent#FLAG_ACTIVITY_SINGLE_TOP}. + + <dt>{@code --activity-clear-task}</dt> + <dd>Include the flag {@link android.content.Intent#FLAG_ACTIVITY_CLEAR_TASK}. + + <dt>{@code --activity-task-on-home}</dt> + <dd>Include the flag {@link android.content.Intent#FLAG_ACTIVITY_TASK_ON_HOME}. + + <dt>{@code --receiver-registered-only}</dt> + <dd>Include the flag {@link android.content.Intent#FLAG_RECEIVER_REGISTERED_ONLY}. + + <dt>{@code --receiver-replace-pending}</dt> + <dd>Include the flag {@link android.content.Intent#FLAG_RECEIVER_REPLACE_PENDING}. + + <dt>{@code --selector}</dt> + <dd>Requires the use of {@code -d} and {@code -t} options to set the intent data and type. + + <dt>{@code <URI> <COMPONENT> <PACKAGE>}</dt> + <dd>You can directly specify a URI, package name, and component name when not qualified + by one of the above options. When an argument is unqualified, the tool assumes the argument + is a URI if it contains a ":" (colon); it assumes the argument is a component name if it + contains a "/" (forward-slash); otherwise it assumes the argument is a package name. + +</dl> +</div><!-- end 'intents' --> +<script> + $(window).hashchange( function(){ + if ((location.hash == "#IntentSpec") && !($("#IntentSpec a").hasClass("expanded"))) { + $("#IntentSpec a").click(); + } + }); +</script> + + + +<h2 id="pm">Using package manager (pm)</h2> + +<p>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:</p> +<pre class="no-pretty-print"> +pm <command> +</pre> + +<p>You can also issue a package manager command directly from adb +without entering a remote shell. For example:</p> +<pre class="no-pretty-print"> +adb shell pm uninstall com.example.MyApp +</pre> + +<p class="table-caption"><strong>Table 3.</strong> Available package manager commands.</p> +<table> +<tr> + <th>Command</th> + <th>Description</th> +</tr> + +<tr> +<td><code> +list packages [options] <FILTER> +</code></td> +<td>Prints all packages, optionally only + those whose package name contains the text in {@code <FILTER>}. <p>Options: +<ul> + <li>{@code -f}: See their associated file. + <li>{@code -d}: Filter to only show disabled packages. + <li>{@code -e}: Filter to only show enabled packages. + <li>{@code -s}: Filter to only show system packages. + <li>{@code -3}: Filter to only show third party packages. + <li>{@code -i}: See the installer for the packages. + <li>{@code -u}: Also include uninstalled packages. + <li>{@code --user <USER_ID>}: The user space to query. +</ul> +</td> +</tr> + +<tr> +<td><code> +list permission-groups +</code></td> +<td>Prints all known permission groups. +</td> +</tr> + +<tr> +<td><code> +list permissions [options] <GROUP> +</code></td> +<td>Prints all known permissions, optionally only + those in {@code <GROUP>}. <p>Options: +<ul> + <li>{@code -g}: Organize by group. + <li>{@code -f}: Print all information. + <li>{@code -s}: Short summary. + <li>{@code -d}: Only list dangerous permissions. + <li>{@code -u}: List only the permissions users will see. +</ul> +</td> +</tr> + +<tr> +<td><code> +list instrumentation +</code></td> +<td>List all test packages. <p>Options: + <ul> + <li>{@code -f}: List the APK file for the test package. + <li>{@code <TARGET_PACKAGE>}: List test packages for only this app. + </ul> +</td> +</tr> + +<tr> +<td><code> +list features +</code></td> +<td>Prints all features of the system. +</td> +</tr> + +<tr> +<td><code> +list libraries +</code></td> +<td>Prints all the libraries supported by the current device. +</td> +</tr> + +<tr> +<td><code> +list users +</code></td> +<td>Prints all users on the system. +</td> +</tr> + +<tr> +<td><code> +path <PACKAGE> +</code></td> +<td>Print the path to the APK of the given {@code <PACKAGE>}. +</td> +</tr> + +<tr> +<td><code> +install [options] <PATH> +</code></td> +<td>Installs a package (specified by {@code <PATH>}) to the system. <p>Options: + <ul> + <li>{@code -l}: Install the package with forward lock. + <li>{@code -r}: Reinstall an exisiting app, keeping its data. + <li>{@code -t}: Allow test APKs to be installed. + <li>{@code -i <INSTALLER_PACKAGE_NAME>}: Specify the installer package name. + <li>{@code -s}: Install package on the shared mass storage (such as sdcard). + <li>{@code -f}: Install package on the internal system memory. + <li>{@code -d}: Allow version code downgrade. + </ul> +</td> +</tr> + +<tr> +<td><code> +uninstall [options] <PACKAGE> +</code></td> +<td>Removes a package from the system. <p>Options: + <ul> + <li>{@code -k}: Keep the data and cache directories around after package removal. + </ul> +</td> +</tr> + +<tr> +<td><code> +clear <PACKAGE> +</code></td> +<td>Deletes all data associated with a package. +</td> +</tr> + +<tr> +<td><code> +enable <PACKAGE_OR_COMPONENT> +</code></td> +<td>Enable the given package or component (written as "package/class"). +</td> +</tr> + +<tr> +<td><code> +disable <PACKAGE_OR_COMPONENT> +</code></td> +<td>Disable the given package or component (written as "package/class"). +</td> +</tr> + +<tr> +<td style="white-space:nowrap"><code> +disable-user [options] <PACKAGE_OR_COMPONENT> +</code></td> +<td><p>Options: + <ul> + <li>{@code --user <USER_ID>}: The user to disable. + </ul> +</td> +</tr> + +<tr> +<td><code> +grant <PACKAGE_PERMISSION> +</code></td> +<td>Grant permissions + to applications. Only optional permissions the application has + declared can be granted. +</td> +</tr> + +<tr> +<td><code> +revoke <PACKAGE_PERMISSION> +</code></td> +<td>Revoke permissions + to applications. Only optional permissions the application has + declared can be revoked. +</td> +</tr> + +<tr> +<td><code> +set-install-location <LOCATION> +</code></td> +<td>Changes the default install location. Location values: +<ul> + <li>{@code 0}: Auto—Let system decide the best location. + <li>{@code 1}: Internal—install on internal device storage. + <li>{@code 2}: External—install on external media. +</ul> +<p class="note"><strong>Note:</strong> This is only intended for debugging; using this can cause + applications to break and other undesireable behavior.</p> +</td> +</tr> + +<tr> +<td><code> +get-install-location +</code></td> +<td>Returns the current install location. Return values: +<ul> + <li>{@code 0 [auto]}: Lets system decide the best location + <li>{@code 1 [internal]}: Installs on internal device storage + <li>{@code 2 [external]}: Installs on external media +</ul> +</td> +</tr> + +<tr> +<td><code> +set-permission-enforced <PERMISSION> [true|false] +</code></td> +<td>Specifies whether the given permission should be enforced. +</td> +</tr> + +<tr> +<td><code> +trim-caches <DESIRED_FREE_SPACE> +</code></td> +<td>Trim cache files to reach the given free space. +</td> +</tr> + +<tr> +<td><code> +create-user <USER_NAME> +</code></td> +<td>Create a new user with the given {@code <USER_NAME>}, + printing the new user identifier of the user. +</td> +</tr> + +<tr> +<td><code> +remove-user <USER_ID> +</code></td> +<td>Remove the user with the given {@code <USER_IDENTIFIER>}, + deleting all data associated with that user +</td> +</tr> + +<tr> +<td><code> +get-max-users +</code></td> +<td>Prints the maximum number of users supported by the device. +</td> +</tr> + +</table> + + +<h2 id="screencap">Taking a device screenshot</h2> + +<p>The {@code screencap} command is a shell utility for taking a screenshot of a device display. +While in a shell, the syntax is: +</p> + +<pre class="no-pretty-print"> +screencap <filename> +</pre> + + +<p>To use the {@code screencap} from the command line, type the following: + +<pre> +$ adb shell screencap /sdcard/screen.png +</pre> + +<p>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:<p> + +<pre> +$ adb shell +shell@ $ screencap /sdcard/screen.png +shell@ $ exit +$ adb pull /sdcard/screen.png +</pre> + + +<h2 id="screenrecord">Recording a device screen</h2> + +<p>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.</p> + +<p class="note"><strong>Note:</strong> Audio is not recorded with the video file.</p> + +<p>A developer can use this file to create promotional or training videos. While in a shell, the syntax is:</p> + +<pre class="no-pretty-print"> +screenrecord [options] <filename> +</pre> + +<p>To use {@code screenrecord} from the command line, type the following: + +<pre> +$ adb shell screenrecord /sdcard/demo.mp4 +</pre> + +<p>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}.</p> + +<p>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:<p> + +<pre> +$ adb shell +shell@ $ screenrecord --verbose /sdcard/demo.mp4 +(press Ctrl-C to stop) +shell@ $ exit +$ adb pull /sdcard/demo.mp4 +</pre> + +<p>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.</p> + +<p>There are some known limitations of the {@code screenrecord} utility that you should be aware + of when using it:</p> + +<ul> + <li>Some devices may not be able to record at their native display resolution. + If you encounter problems with screen recording, try using a lower screen resolution.</li> + <li>Rotation of the screen during recording is not supported. If the screen does rotate during + recording, some of the screen is cut off in the recording.</li> +</ul> + + +<p class="table-caption"><strong>Table 4.</strong> {@code screenrecord} options</p> + +<table> + <tr> + <th>Options</th> + <th>Description</th> + </tr> + + <tr> + <td><code>--help</code> + </td> + <td>Displays command syntax and options</td> + </tr> + + <tr> + <td style="white-space:nowrap"> + <code>--size <WIDTHxHEIGHT></code> + </td> + <td>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.</td> + </tr> + + <tr> + <td><code>--bit-rate <RATE></code></td> + <td>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: + <pre>screenrecord --bit-rate 6000000 /sdcard/demo.mp4</pre> + </td> + </tr> + + <tr> + <td><code>--time-limit <TIME></code></td> + <td>Sets the maximum recording time, in seconds. The default and maximum value is 180 + (3 minutes).</td> + </tr> + + <tr> + <td><code>--rotate</code></td> + <td>Rotates the output 90 degrees. This feature is experimental.</td> + </tr> + + <tr> + <td><code>--verbose</code></td> + <td>Displays log information on the command-line screen. If you do not set this option, + the utility does not display any information while running.</td> + </tr> + +</table> + + +<h2 id="othershellcommands">Other shell commands</h2> + +<p>For a list of all the available shell programs, use the following command:</p> + +<pre class="no-pretty-print">adb shell ls /system/bin</pre> + +<p>Help is available for most of the commands. </p> + +<p>Table 5 lists some of the more common adb shell commands.</p> + +<p class="table-caption"><strong>Table 5.</strong> Some other adb shell commands</p> +<table> +<tr> + <th>Shell Command</th> + <th>Description</th> + <th>Comments</th> +</tr> + +<tr> +<td><code>dumpsys</code></td> +<td>Dumps system data to the screen.</td> +<td rowspan=4">The <a href="{@docRoot}tools/debugging/ddms.html">Dalvik Debug Monitor Server</a> +(DDMS) tool offers integrated debug environment that you may find easier to use.</td> +</tr> + +<tr> +<td><code>dumpstate</code></td> +<td>Dumps state to a file.</td> +</tr> + +<tr> +<td><code>logcat [option]... [filter-spec]...</code></td> +<td>Enables system and app logging and prints output to the screen. </td> +</tr> + +<tr> +<td><code>dmesg</code></td> +<td>Prints kernel debugging messages to the screen. </td> +</tr> + +<tr> +<td><code>start</code></td> +<td>Starts (restarts) an emulator/device instance.</td> +<td> </td> +</tr> + +<tr> +<td><code>stop</code></td> +<td>Stops execution of an emulator/device instance.</td> +<td> </td> +</tr> + +</table>
\ No newline at end of file diff --git a/docs/html/tools/studio/eclipse-transition-guide.jd b/docs/html/tools/studio/eclipse-transition-guide.jd new file mode 100644 index 0000000..aaacbe3 --- /dev/null +++ b/docs/html/tools/studio/eclipse-transition-guide.jd @@ -0,0 +1,773 @@ +page.title=Transition Guide for Eclipse ADT +@jd:body + + +<div id="qv-wrapper"> +<div id="qv"> + +<h2>In this document</h2> + <ol> + <li><a href="#project-structure">Project Structure</a></li> + <li><a href="#manifest-settings">Manifest Settings</a></li> + <li><a href="#dependencies">Dependencies</a></li> + <li><a href="#build-process">Gradle-based Build Process</a></li> + <li><a href="#debug-inspect">Debugging and Code Inspections</a></li> + <li><a href="#resource-optimization">Resource Optimization</a></li> + <li><a href="#signing">App Signing</a></li> + <li><a href="#support-lib">Android Support Repository and Google Play services Repository</a></li> + <li><a href="#app-package">App Packaging</a></li> + <li><a href="#software-updates">Software Updates </a></li> + <li><a href="#version-control">Version Control</a></li> + </ol> + + <h2>See also</h2> + <ol> + <li><a class="external-link" + href="http://confluence.jetbrains.com/display/IntelliJIDEA/FAQ+on+Migrating+to+IntelliJ+IDEA"> + IntelliJ FAQ on migrating to IntelliJ IDEA</a></li> + <li><a class="external-link" + href="https://confluence.jetbrains.com/display/IntelliJIDEA/IntelliJ+IDEA+for+Eclipse+Users"> + IntelliJ IntelliJ for Eclipse Users</a></li> + <li><a href="{@docRoot}tools/studio/index.html">Android Studio Overview</a> </li> + </ol> + +</div> +</div> + + +<p>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.</p> + +<h2 id="project-structure">Project Structure </h2> +<p>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 <code>gradle.build</code> file for +build specification, and the files under {@code src/androidTest} directory for test case creation. </p> + +<p>You can also customize the view of the project files in Android Studio to focus on specific +aspects of your app development: </p> + +<ul> + <li><em>Packages</em> </li> + <li><em>Project Files</em> </li> + <li><em>Scratches</em> </li> + <li><em>Problems</em> </li> + <li><em>Production</em> </li> + <li><em>Tests</em> </li> +</ul> + + +<p>The following table shows the general mapping of the Eclipse ADT project structure and file +locations to Android Studio.</p> + +<p class="table-caption" id="table-project-structure-mapping"> + <strong>Table 1.</strong> Project structure mapping.</p> + +<table> + <tr> + <th scope="col">Eclipse ADT</th> + <th scope="col">Android Studio</th> + </tr> + + <tr> + <td>Workspace </td> + <td>Project </td> + </tr> + + <tr> + <td>Project </td> + <td>Module </td> + </tr> + + <tr> + <td>Project-specific JRE </td> + <td>Module JDK </td> + </tr> + + <tr> + <td>Classpath variable </td> + <td>Path variable</td> + </tr> + + <tr> + <td>Project dependency</td> + <td>Module dependency</td> + </tr> + + <tr> + <td>Library Module</td> + <td>Library </td> + </tr> + + <tr> + <td><code>AndroidManifest.xml</code></td> + <td><code>app/src/main/AndroidManifest.xml</code> </td> + </tr> + <tr> + <td><code>assets/</code></td> + <td><code>app/src/main/assets</code> </td> + </tr> + <tr> + <td><code>res/</code></td> + <td><code>app/src/main/res/</code> </td> + </tr> + <tr> + <td><code>src/</code></td> + <td><code>app/src/main/java/ </code> </td> + </tr> + <tr> + <td><code>tests/src/</code></td> + <td><code>app/src/androidTest/java/</code> </td> + </tr> + + </table> + + + +<p>Table 2 shows Eclipse ADT and Android Studio project views. </p> + +<p class="table-caption" id="table2"> + <strong>Table 2.</strong> Comparing project views.</p> +<table> + <tbody><tr> + <th>Eclipse ADT</th> + <th>Android Studio Project View</th> + <th>Android Studio Android View</th> + </tr> + <tr> + <td><img src="{@docRoot}images/tools/eclipse-notepad-pre-import--structure.png"/> </td> + <td><img src="{@docRoot}images/tools/studio-import-project-structure-project.png"/> </td> + <td><img src="{@docRoot}images/tools/studio-import-project-structure-android.png"/> </td> + </tr> + </tbody> +</table> + + +<p class="note"><strong>Note:</strong> Multiple instances of Android Studio can be used to develop +independent projects. </p> + + + + +<h2 id="manifest-settings">Manifest Settings</h2> +<p>Android Studio and <a href="http://www.gradle.org">Gradle</a>-based builds support +<a href="{@docRoot}tools/building/configuring-gradle.html#workBuildVariants"> build variants</a>, +which are combinations of <code>productFlavor</code> and <code>buildTypes</code>, to customize +your build outputs. To support these custom builds, several elements in the +<code>AndroidManifest.xml</code> file are now properties in the <code>defaultConfig</code> and +<code>productFlavors</code> blocks in the <code>build.gradle</code> file. The import process +copies these manifest settings to the properties in the <code>build.gradle</code> file. +These properties overwrite the settings in any other manifest files as shown in table 3. </p> + +<p class="table-caption" id="table-manifest-gradle-settings"> + <strong>Table 3.</strong> Manifest and Gradle property settings.</p> +<table> + <tr> + <th scope="col">Manifest Setting</th> + <th scope="col">build.gradle Setting</th> + </tr> + <tr> + <td><code><uses-sdk</code> <br> + <p><code>android:minSdkVersion</code></p> + <p><code>android:targetSdkVersion /></code></p> + </td> + <td> <br> + <p><code>minSdkVersion</code></p> + <p><code>targetSdkVersion</code></p> </td> + </tr> + <tr> + <td><code><manifest</code> + <p>package (Required in the default manifest file.) </p> + <p><code>android:versionCode</code></p> + <p><code>android:versionName /></code></p> + </td> + <td> <br> + <p><code>applicationId</code> (See + <a href="{@docRoot}tools/studio/index.html#app-id"> Application ID + for Package Identification</a>)</p> + <p><code>versionCode</code></p> + <p><code>versionName</code></p> </td> + </tr> + + </table> + + +<p>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.</p> + +<p>The <code>package</code> element must still be specified in the manifest file. It is used in +your source code to refer to your <code>R</code> class and to resolve any relative activity/service +registrations. </p> + +<p class="note"><strong>Note:</strong> When multiple manifests are present in your app, for +example a library manifest and a <code>src/main/</code> 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 +<a href="{@docRoot}tools/building/manifest-merger.html"> Manifest Merger</a>. </p> + + +<h2>Application ID for package identification </h2> +<p>With the Android build system, the <code>applicationId</code> attribute is used to +uniquely identify application packages for publishing. The application ID is set in the +<code>android</code> section of the <code>build.gradle</code> file. This field is populated in the +build file as part of the migration process. </p> + +<pre> +apply plugin: 'com.android.application' + +android { + compileSdkVersion 19 + buildToolsVersion "19.1" + + defaultConfig { + <strong>applicationId "com.example.my.app"</strong> + minSdkVersion 15 + targetSdkVersion 19 + versionCode 1 + versionName "1.0" + } + ... +</pre> + +<p class="note"><strong>Note:</strong> The <code>applicationId</code> is specified only in your +<code>build.gradle</code> file, and not in the <code>AndroidManifest.xml</code> file.</p> + +<p><a href="{@docRoot}tools/building/configuring-gradle.html#workBuildVariants">Build variants</a> +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 +<code>.debug</code> suffix to the application ID of the <code>pro</code> and <code>free</code> +product flavors: </p> + +<pre> +productFlavors { + pro { + applicationId = "com.example.my.pkg.pro" + } + free { + applicationId = "com.example.my.pkg.free" + } +} + +buildTypes { + debug { + applicationIdSuffix ".debug" + } +} +.... +</pre> + + + +<h2 id="dependencies">Dependencies</h2> +<p>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 <code>build.gradle</code> file. The declarations include a +<a href="#scopes">dependency scope</a>, such as +<code>compile</code>, to specify in which builds the dependency is included. </p> + +<p>The following example shows how to add an external library JAR dependency so it's included in +each compile:</p> + +<pre> +dependencies { + compile files('libs/*.jar') +} + +android { + ... +} +</pre> + +<p class="note"><strong>Note:</strong> Android Studio supports the Android ARchive (AAR) format +for the distribution of Android library projects as dependencies. For more information, see +<a href="{@docRoot}tools/building/configuring-gradle.html">Configuring Gradle Builds</a>. </p> + + +<p>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. </p> + +<p>Android Studio enables access to Maven, JCenter, and Ivy repositories with the +<code>repositories</code> block in the <code>build.gradle</code> as a shortcut to specifying +the URL of the repository. + +<p>If there are required repositories not declared in the <code>build.gradle</code> file, first add +the repository to the <code>repositories</code> 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 <code>mavenCentral()</code> property: </p> + +<pre> +repositories { + mavenCentral() +} + +android { + ... +} + +dependencies { + compile 'com.google.guava:guava:11.0.2' + instrumentationtestCompile 'com.squareup.fast-android:1:0.4' +} + +</pre> + +<p>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 +<a href="http://www.gradle.org">Gradle</a> projects. If a dependency has dependencies of its own, +those dependencies are also included in the new Android Studio project. </p> + + +<p class="note"><strong>Note:</strong> If there were references to Eclipse ADT workspace library +files in the <code>project.properties</code> or <code>.classpath</code> files +that were not imported from the Eclipse project, you can now add dependencies to these library files +in the <code>build.gradle</code> file. For more information, see +<a href="{@docRoot}tools/building/configuring-gradle.html">Configuring Gradle Builds</a>. </p> + + +<h3 id="scopes">Dependency and compilation scopes </h3> +<p>Android Studio supports compilation scopes to customize which dependencies get +included in each build, for example assigning different dependencies to different +<a href="{@docRoot}tools/building/configuring-gradle.html#workBuildVariants"> build variants</a>.</p> + +<p>This list shows the Android Studio scope names and definitions: </p> + +<ul> + <li>compile - <code>compile</code> </li> + <li>run time - <code>package</code></li> + <li>testCompile - <code>AndroidTestCompile</code></li> + <li>testRuntime - <code>AndroidTestRunPackage</code></li> + <li>buildTypeCompile - <code>buildTypeCompile</code> </li> + <li>productFlavorCompile - <code>productFlavorCompile</code> </li> +</ul> + +<p class="note"><strong>Note:</strong> Dependencies for library projects must be added with the +<code>compile</code> scope. </p> + + +<p>With the <a href="http://www.gradle.org">Gradle</a>-based DSL, you can also add custom +dependency scopes, such as <code>betaCompile file('libs/protobug.jar')</code> to define a beta +build dependency. </p> + +<p>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: </p> + +<ul> +<li><code>compile</code> - for the main application. </li> +<li><code>androidTestCompile</code> - for the test application. </li> +<li><code>debugCompile</code> - for the debug buildType application.</li> +<li><code>releaseCompile</code> - for the release buildType application. </li> +</ul> + +<p class="note"><strong>Note:</strong> Because it’s not possible to build an APK that does not +have an associated <code>buildType</code>, the APK built from your app is always configured with +at least two dependency and compile configurations: <code>compile</code> and +<code>debugCompile</code>. </p> + +<p>Unlike Eclipse ADT, by default Android Studio does not compile your code when there are changes. +Use the <strong>File > Settings > Build, Execution, Deployment Compiler</strong> option +to enable automatic compilation. </p> + + + +<h2 id="build-process">Gradle-based Build Process </h2> +<p>Android Studio imports the Eclipse ADT Ant-based +build tasks and converts the tasks to <a href="http://www.gradle.org">Gradle</a>-based build tasks. +These new build tasks include the +main <code>assemble</code> task and at least two outputs based on the default build types: +a <code>debug</code> APK and a +<code>release</code> APK. Each of these build tasks has its own Android build system anchor task +to facilitate building them independently: </p> +<ul> + <li><code>assemble</code></li> + <li><code>assembleDebug</code></li> + <li><code>assembleRelease</code></li> +</ul> + +<p>In Android Studio, you can view all the supported build tasks in the +<em>Gradle</em> project tab. </p> + +<p>With the <a href="http://www.gradle.org">Gradle</a>-based build system, Android Studio uses a +<a href="http://www.gradle.org">Gradle</a> 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). </p> + +<p>Unlike Eclipse ADT with dependent plugin and build updates, the <code>build.gradle</code> +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. </p> + +<p>For more details about the Android Studio build system, see +<a href="{@docRoot}sdk/installing/studio-build.html">Build System Overview</a>.</p> + +<h3>Using the Android Studio build system's declarative logic </h3> +<p>In contrast with the XML statements in Ant build files, the Android build system and +<a href="http://www.gradle.org">Gradle</a> 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 <code>versionCode</code> +in build outputs: </p> + +<pre> +def getVersionCode) { + def code = … + return code +} + +android { + defaultConfig { + versionCode getVersionCode() + … + } +} +</pre> + +<p>This example shows how to append <em>debug</em> to your package and version names used in the +<code>debug</code> build variant of your app: </p> + +<pre> +android { + buildTypes { + debug { + packageNameSuffix ‘.debug’ + versionNameSuffix ‘-DEBUG’ + } + beta { + … + } + } +} +</pre> + + +<p>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 +<code>debuggable true</code> property to the <code>release</code> build type in the +<code>build.gradle</code> file to build an identical debuggable version of the release package. </p> + +<pre> +android { + buildTypes { + debugRelease.initWith(buildTypes.release) + debugRelease { + debuggable true + packageNameSuffix '.debugrelease' + signingConfig signingConfigs.debug + } + + } + sourceSets.debugRelease.setRoot('src/release') +} +</pre> + + + + + + +<h2 id="debug-inspect">Debugging and Code Inspections</h2> +<p>Using code inspection tools such as <a href="{@docRoot}tools/help/lint.html">lint</a> is a +standard part of Android development. Android Studio extends +<a href="{@docRoot}tools/help/lint.html">lint</a> support with additional +<a href="{@docRoot}tools/help/lint.html">lint</a> checks and supports Android +<a href="{@docRoot}tools/debugging/annotations.html">annotations</a> 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. </p> + +<p>For more information on enabling <a href="{@docRoot}tools/help/lint.html">lint</a> inspections +and running <a href="{@docRoot}tools/help/lint.html">lint</a>, +see <a href="{@docRoot}tools/debugging/improving-w-lint.html">Improving Your Code with lint</a>. +For more information about using annotations, see +<a href="{@docRoot}tools/debugging/annotations.html#annotations">Improving your Code with +Annotations</a>. </p> + +<p>In addition to code inspection, Android Studio provides an integrated +<a href="{@docRoot}tools/studio/index.html#mem-cpu">memory and CPU monitor</a> 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. </p> + + + +<h2 id="resource-optimization">Resource Optimization </h2> +<p>After importing and building your app, Android Studio supports several +<a href="http://www.gradle.org">Gradle</a>-based properties to help you minimize your app's +resource utilization. </p> + + +<h3>Resource shrinking</h3> +<p>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.</p> + +<p>Use the <code>shrinkResources</code> attribute in the <code>buildType</code> block in your +<code>build.gradle</code> file to enable resource shrinking. For example, if your application is +using <a href="{@docRoot}google/play-services/index.html">Google Play services</a> +to access Google Drive functionality, and you are not currently using +<a href="{@docRoot}google/play-services/plus.html">Google+ Sign In</a>, then +this setting removes the various drawable assets for the <code>SignInButton</code> buttons. </p> + +<p class="note"><strong>Note:</strong> Resource shrinking works in conjunction with code shrinking +tools, such as <a href="{@docRoot}tools/help/proguard.html">ProGuard</a>. </p> + +<p>To enable resource shrinking, update the <code>buildTypes</code> block in the +<code>build.gradle</code> file to include <code>minifyEnabled true</code>, +<code>shrinkResources true</code>, and <code>proguardFiles</code> settings as shown in the +following example <a href="http://www.gradle.org">Gradle</a> build file.</p> + +<pre> +android { + ... + + buildTypes { + release { + minifyEnabled true + shrinkResources true + proguardFiles getDefaultProguardFile('proguard-android.txt'), + 'proguard-rules.pro' + } + } +} +</pre> + + + +<h3>Filtering language resources</h3> +<p>Use the <code>resConfig</code> attribute in your <code>build.gradle</code> file +to filter the locale resources included in your packaged app. This filtering can be especially +useful when library dependencies such as <code>appcompat-v7</code> and other libraries such as +<code>google-play-services_lib</code> are included in your app. </p> + +<p>The following example limits the locale resources to three language settings: <code>en</code>, +<code>de</code>, and <code>es</code>:</p> + +<pre> +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. + } +... + +</pre> + + + +<h4>Filtering bundled resources</h4> +<p>You can also use the <code>resConfig</code> build setting to limit the bundled resources +in any resource folder. For example, you could also add <code>resConfigs</code> +settings for density folders, such as <code>mdpi</code> or <code>hdpi</code> to limit the drawable +resources that are packaged in your <code>APK</code> file. This example limits the app's +bundled resources to medium-density (MDPI) and high-density (HDPI) resources. </p> + +<pre> +android { + defaultConfig { + ... + resConfigs "mdpi", "hdpi" + } +} +</pre> + +For more information about screen and resource densities, see +<a href="{@docRoot}guide/practices/screens_support.html">Supporting Multiple Screens</a> +and <a href="{@docRoot}training/multiscreen/screendensities.html">Supporting Different Densities</a>. + + +<h3>Resource merging </h3> +<p>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. </p> + +<p>The resource merging process looks for identical resources in the following <code>/res/</code> +folders: </p> +<ul> + <li>AAR bundles of library project dependencies</li> + <li><code>src/main/</code> </li> + <li><code>src/<em>productFlavor</em>/</code> </li> + <li><code>src/<em>buildType</em>/</code> </li> +</ul> + +<p>Identical resources are merged in the following low to high priority order: </p> +<pre> +dependencies --> src/main/ --> src/productFlavor/ --> src/buildType/ +</pre> + +<p>For example, if the <code>res/ic_menu.png</code> file is included in both the +<code>src/main/res/</code> and <code>src/productFlavor/res/</code> folders, the resources are merged +so only the file with the higher priority, in this case the <code>src/productFlavor/res/</code> +file, is included in the APK file. </p> + +<p class="note"><strong>Note:</strong> Identical resources in the same source set are not merged +and instead generate a resource merge error. This can happen if the <code>sourceSet</code> property +in the <code>build.gradle</code> file is used to define multiple source sets, for example +<code>src/main/res/</code> and <code>src/main/res2/</code>, and these folders contain identical +resources. </p> + + + + +<h2 id="signing">App Signing and ProGuard </h2> +<p>Based on the imported Eclipse ADT app settings, Android Studio automatically sets up your app +signing and maintains any ProGuard settings. </p> + +<h3>App Signing</h3> +<p>If your app used a debug certificate in Eclipse ADT, Android Studio continues to reference that +certificate. Otherwise, the <code>debug</code> configuration uses the Android Studio generated +debug keystore, with a known password and a default key with a known password located in +<code>$HOME/.android/debug.keystore</code>. The <code>debug</code> build type is set to use this +debug <code>SigningConfig</code> automatically when you run or debug your project +from Android Studio. </p> + +<p>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 <code>build.gradle</code> file or use the <strong> Build > Generate Signed APK</strong> menu +option to open the Generate Signed APK Wizard. For more information about signing your app, see +<a href="{@docRoot}tools/publishing/app-signing.html">Signing Your Applications</a>. </p> + + +<h3>ProGuard</h3> +<p>If the <a href="{@docRoot}tools/help/proguard.html">ProGuard</a> option is specified in the +<code>project.properties</code> file in the Eclipse ADT project, Android Studio imports the +<a href="{@docRoot}tools/help/proguard.html">ProGuard</a> files and adds the +<a href="{@docRoot}tools/help/proguard.html">ProGuard</a> settings to the +<code>build.gradle</code> file. <a href="{@docRoot}tools/help/proguard.html">ProGuard</a> is +supported through the <code>minifyEnabled</code> property as shown in this example. </p> + +<pre> +android { + buildTypes { + release { + minifyEnabled true + proguardFile getDefaultProguardFile('proguard-android.txt') + } + } + + productFlavors { + flavor1 { + } + flavor2 { + proguardFile 'some-other-rules.txt' + } + } +} + +</pre></p> + + + + +<h2 id="support-lib">Android Support Repository and Google Play services Repository</h2> +<p>While Eclipse ADT uses the Android <a href="{@docRoot}tools/support-library/index.html">Support +Library</a> 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. </p> + +<p>In Eclipse, in order to use a +<a href="{@docRoot}tools/support-library/index.html">Support Library</a>, you must modify your +project's classpath dependencies within your development environment for each +<a href="{@docRoot}tools/support-library/index.html">Support Library</a> 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, +<a href="{@docRoot}tools/help/proguard.html">ProGuard</a> exclusion rules, and custom lint rules +at build time. </p> + +<p>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). <p/> + + +<h2 id="app-package">App Packaging</h2> +<p>The Android build system introduces the use of the <code>applicationId</code> attribute to +uniquely identify application packages for publishing. The application ID is set in the +<code>android</code> section of the <code>build.gradle</code> file. </p> + +<p>The <code>applicationId</code> is specified only in your <code>build.gradle</code> file, and +not in the +<code>AndroidManifest.xml</code> 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 <code>applicationIdSuffix</code> property to the build type in the +<code>build.gradle</code> file to append an identifier, such as '.debug', to the application ID +generated for each product flavor. </p> + + + +<h2 id="software-updates">Software Updates</h2> +<p>Android Studio provides several levels of update and maintenance to help you keep Android Studio +up-to-date based on your code-level preference: </p> + +<ul> + <li><strong>Canary channel</strong>: Canary builds provide bleeding edge releases and are updated + about weekly. These builds do get tested, but are still subject to bugs, as these are + early releases. This is not recommended for production.</li> + <li><strong>Dev channel</strong>: Dev builds are canary builds that passed initial testing and + usage. They are updated roughly bi-weekly or monthly.</li> + <li><strong>Beta channel</strong>: Beta builds provide beta-quality releases for final testing + and feedback before a production release.</li> + <li><strong>Stable channel</strong>: Stable builds provide stable, production-ready release + versions.</li> +</ul> + + + +<h2 id="version-control">Version Control </h2> +<p>Eclipse ADT supports version control through the use of plugins, such as the EGit and Subversive +plug-ins. </p> + +<p>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. </p> + +<p>After importing your Eclipse ADT app into Android Studio, use the +Android Studio <em>VCS</em> 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. </p> + +<p class="note"><strong>Note:</strong> You can also use the +<strong>File > Setting > Version Control</strong> menu option to setup and modify the version +control settings. </p> + +<h3>Files to ignore </h3> +<p>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 <code>.gitignore</code>, for the project and each app module. +Typically, the following files are excluded from version control: </p> + +<ul> + <li>.gradle </li> + <li>/local.properties </li> + <li>/.idea/workspace.xml </li> + <li>/.idea/libraries </li> + <li>.DS_Store</li> + <li>/build </li> + <li>/captures </li> +</ul> diff --git a/docs/html/tools/studio/index.jd b/docs/html/tools/studio/index.jd index 0113347..fa6d987 100644 --- a/docs/html/tools/studio/index.jd +++ b/docs/html/tools/studio/index.jd @@ -175,7 +175,7 @@ To configure custom build settings in an Android Studio project, see <a href="{@docRoot}tools/building/configuring-gradle.html">Configuring Gradle Builds</a>.</p> -<h3>Application ID for package identification </h3> +<h3 id="app-id">Application ID for package identification </h3> <p>With the Android build system, the <em>applicationId</em> attribute is used to uniquely identify application packages for publishing. The application ID is set in the <em>android</em> section of the <code>build.gradle</code> file. diff --git a/docs/html/tools/tools_toc.cs b/docs/html/tools/tools_toc.cs index 82515d4..abfa030 100644 --- a/docs/html/tools/tools_toc.cs +++ b/docs/html/tools/tools_toc.cs @@ -189,71 +189,13 @@ class="en">Tools Help</span></a></div> <span class="en">Configuring Gradle Builds</span></a></li> <li><a href="<?cs var:toroot ?>tools/building/plugin-for-gradle.html"> <span class="en">Android Plugin for Gradle</span></a></li> + <li><a href="<?cs var:toroot ?>tools/building/manifest-merge.html"> + <span class="en">Manifest Merging</span></a></li> <li><a href="<?cs var:toroot ?>tools/building/multidex.html"> <span class="en">Apps Over 65K Methods</span></a></li> </ul> </li><!-- end of build system --> -<!-- Performance Tools menu--> - <li class="nav-section"> - <div class="nav-section-header"> - <a href="<?cs var:toroot ?>tools/performance/index.html">Peformance Tools</a> - </div> - <ul> - <li><a href="<?cs var:toroot ?>tools/performance/debug-gpu-overdraw/index.html"> - Overdraw Debugger</a> - </li> - <li><a href="<?cs var:toroot ?>tools/performance/profile-gpu-rendering/index.html"> - Rendering Profiler</a> - </li> - <li class="nav-section"> - <div class="nav-section-header"> - <a href="<?cs var:toroot ?>tools/performance/hierarchy-viewer/index.html"> - Hierarchy Viewer</a></div> - <ul> - <li><a href="<?cs var:toroot ?>tools/performance/hierarchy-viewer/setup.html"><span - class="en">Setup</span></a> - </li> - <li><a href="<?cs var:toroot ?>tools/performance/hierarchy-viewer/profiling.html"><span - class="en">Profiling</span></a> - </li> - </ul> - </li> - <li class="nav-section"> - <div class="nav-section-header"> - <a href="<?cs var:toroot ?>tools/performance/comparison.html"> - Memory Profilers</a></div> - <ul> - <li><a href="<?cs var:toroot ?>tools/performance/memory-monitor/index.html"><span - class="en">Memory Monitor</span></a> - </li> - <li><a href="<?cs var:toroot ?>tools/performance/heap-viewer/index.html"><span - class="en">Heap Viewer</span></a> - </li> - <li><a href="<?cs var:toroot ?>tools/performance/allocation-tracker/index.html"><span - class="en">Allocation Tracker</span></a> - </li> - </ul> - </li> - <li><a href="<?cs var:toroot ?>tools/performance/traceview/index.html"> - Traceview</a> - </li> - <li><a href="<?cs var:toroot ?>tools/performance/systrace/index.html"> - Systrace</a> - </li> - <li class="nav-section"> - <div class="nav-section-header"> - <a href="<?cs var:toroot ?>tools/performance/batterystats-battery-historian/index.html"> - Battery Profilers</a></div> - <ul> - <li><a href="<?cs var:toroot ?>tools/performance/batterystats-battery-historian/charts.html"><span - class="en">Historian Charts</span></a> - </li> - </ul> - </li> - </ul> - </li><!-- End Performance Tools menu--> - <!-- Testing Tools menu--> <li class="nav-section"> @@ -351,7 +293,15 @@ class="en">Data Binding Library</span></a></div> <span class="en">Eclipse with ADT</span></a> </div> <ul> - <li><a href="<?cs var:toroot ?>sdk/installing/migrate.html">Migrating to Android Studio</a></li> + <li class="nav-section"> + <div class="nav-section-header"><a href="<?cs var:toroot ?>sdk/installing/migrate.html"> + <span class="en">Migrating to Android Studio</span></a></div> + <ul> + <li><a href="<?cs var:toroot ?>tools/studio/eclipse-transition-guide.html"> + Transition Guide</span></a> </li> + </ul> + </li> + <li><a href="<?cs var:toroot ?>sdk/installing/installing-adt.html"> <span class="en">Installing the Eclipse Plugin</span></a></li> <li><a href="<?cs var:toroot ?>tools/projects/projects-eclipse.html">Managing Projects</a></li> diff --git a/docs/html/training/enterprise/app-compatibility.jd b/docs/html/training/enterprise/app-compatibility.jd index 216a799..419ba89 100644 --- a/docs/html/training/enterprise/app-compatibility.jd +++ b/docs/html/training/enterprise/app-compatibility.jd @@ -250,14 +250,14 @@ href="{@docRoot}tools/help/adb.html">Android Debug Bridge</a> (adb) shell support the <code>--user</code> flag, which lets you specify which user to run as. By specifying a user, you can choose whether to run as the unmanaged or managed profile. For -more information, see <a href="{@docRoot}tools/help/adb.html#am">Android Debug -Bridge: Using activity manager (am)</a>.</li> +more information, see <a href="{@docRoot}tools/help/shell.html#am">ADB +Shell Commands</a>.</li> <li>To find the active users on a device, use the adb package manager's <code>list users</code> command. The first number in the output string is the user ID, which you can use with the <code>--user</code> flag. For more -information, see <a href="{@docRoot}tools/help/adb.html#pm">Android Debug -Bridge: Using package manager (pm)</a>.</li> +information, see <a href="{@docRoot}tools/help/shell.html#pm">ADB Shell +Commands</a>.</li> </ul> diff --git a/docs/html/training/volley/requestqueue.jd b/docs/html/training/volley/requestqueue.jd index 5e892bf..6d19cee 100644 --- a/docs/html/training/volley/requestqueue.jd +++ b/docs/html/training/volley/requestqueue.jd @@ -139,7 +139,8 @@ rotates the device). <p>Here is an example of a singleton class that provides {@code RequestQueue} and {@code ImageLoader} functionality:</p> -<pre>private static MySingleton mInstance; +<pre>public class MySingleton { + private static MySingleton mInstance; private RequestQueue mRequestQueue; private ImageLoader mImageLoader; private static Context mCtx; |
