From 5cdf5fdcba846bd4659084f5f9e5a1e367dbea5d Mon Sep 17 00:00:00 2001 From: Scott Main Date: Tue, 11 May 2010 14:21:53 -0700 Subject: [PATCH] docs: add document about app install location Change-Id: Ife7d79ce8374f3435f4850cbf97d163e69bf8d26 --- docs/html/guide/appendix/install-location.jd | 197 ++++++++++++++++++ docs/html/guide/guide_toc.cs | 9 +- .../guide/topics/manifest/manifest-element.jd | 1 + 3 files changed, 204 insertions(+), 3 deletions(-) create mode 100644 docs/html/guide/appendix/install-location.jd diff --git a/docs/html/guide/appendix/install-location.jd b/docs/html/guide/appendix/install-location.jd new file mode 100644 index 0000000000000..77cebc62a43cf --- /dev/null +++ b/docs/html/guide/appendix/install-location.jd @@ -0,0 +1,197 @@ +page.title=App Install Location +@jd:body + + +
+
+ +

Quickview

+
    +
  • You can allow your application to install on the device's external storage.
    • +
  • Some types of applications should not allow installation on the external +storage.
    • +
  • Installing on the external storage is ideal for large applications that are not tightly +integrated with the system (most commonly, games).
    • +
+ +

In this document

+
    +
  1. Backward Compatibility
    2. +
  2. Applications That Should NOT Install on External Storage
    3. +
  3. Applications That Should Install on External Storage
    4. +
+ +

See also

+
    +
  1. +<manifest>
    2. +
+ +
+
+ +

Beginning with API Level 8, you can allow your application to be installed on the +external storage (for example, the device's SD card). This is an optional feature you can declare +for your application with the {@code +android:installLocation} manifest attribute. If you do +not declare this attribute, your application will be installed on the internal storage +only and it cannot be moved to the external storage.

+ +

To allow the system to install your application on the external storage, modify your +manifest file to include the {@code +android:installLocation} attribute in the <manifest> element, +with a value of either "{@code preferExternal}" or "{@code auto}". For example:

+ +
+<manifest xmlns:android="http://schemas.android.com/apk/res/android"
+    android:installLocation="preferExternal"
+    ... >
+
+ +

If you declare "{@code preferExternal}", you request that your application be installed on the +external storage, but the system does not guarantee that your application will be installed on +the external storage. If the external storage is full, the system will install it on the internal +storage. The user can also move your application between the two locations.

+ +

If you declare "{@code auto}", you indicate that your application may be installed on the +external storage, but you don't have a preference of install location. The system will +decide where to install your application based on several factors. The user can also move your +application between the two locations.

+ +

When your application is installed on the external storage:

+ + +

Warning: When the user enables USB mass storage to share files +with a computer or unmounts the SD card via the system settings, the external storage is unmounted +from the device and all applications running on the external storage are immediately killed.

+ + + +

Backward Compatibility

+ +

The ability for your application to install on the external storage is a feature available only +on devices running API Level 8 (Android 2.2) or greater. Existing applications that were built prior +to API Level 8 will always install on the internal storage and cannot be moved to the external +storage (even on devices with API Level 8). However, if your application is designed to support an +API Level lower than 8, you can choose to support this feature for devices with API Level 8 +or greater and still be compatible with devices using an API Level lower than 8.

+ +

To allow installation on external storage and remain compatible with versions lower than API +Level 8:

+
    +
  1. Include the {@code android:installLocation} attribute with a value of "{@code auto}" or +"{@code preferExternal}" in the <manifest> +element.
    2. +
  2. Leave your {@code android:minSdkVersion} attribute as is (something less +than "8") and be certain that your application code uses only APIs compatible with that +level.
    3. +
  3. In order to compile your application, change your build target to API Level 8. This is +necessary because older Android libraries don't understand the {@code android:installLocation} +attribute and will not compile your application when it's present.
    4. +
+ +

When your application is installed on a device with an API Level lower than 8, the {@code +android:installLocation} attribute is ignored and the application is installed on the internal +storage.

+ +

Caution: Although XML markup such as this will be ignored by +older platforms, you must be careful not to use programming APIs introduced in API Level 8 +while your {@code minSdkVersion} is less than "8", unless you perform the work necessary to +provide backward compatiblity in your code. For information about building +backward compatibility in your application code, see the Backward Compatibility +article.

+ + + +

Applications That Should NOT Install on External Storage

+ +

When the user enables USB mass storage to share files with their computer (or otherwise +unmounts or removes the external storage), any application +installed on the external storage and currently running is killed. The system effectively becomes +unaware of the application until mass storage is disabled and the external storage is +remounted on the device. Besides killing the application and making it unavailable to the user, +this can break some types of applications in a more serious way. In order for your application to +consistently behave as expected, you should not allow your application to be +installed on the external storage if it uses any of the following features, due to the cited +consequences when the external storage is unmounted:

+ +
+
Services
+
Your running {@link android.app.Service} will be killed and will not be restarted when +external storage is remounted. You can, however, register for the {@link +android.content.Intent#ACTION_EXTERNAL_APPLICATIONS_AVAILABLE} broadcast Intent, which will notify +your application when applications installed on external storage have become available to the +system again. At which time, you can restart your Service.
+
Alarm Services
+
Your alarms registered with {@link android.app.AlarmManager} will be cancelled. You must +manually re-register any alarms when external storage is remounted.
+
Input Method Engines
+
Your IME will be +replaced by the default IME. When external storage is remounted, the user can open system settings +to enable your IME again.
+
Live Wallpapers
+
Your running Live Wallpaper +will be replaced by the default Live Wallpaper. When external storage is remounted, the user can +select your Live Wallpaper again.
+
Live Folders
+
Your Live Folder will be +removed from the home screen. When external storage is remounted, the user can add your Live Folder +to the home screen again.
+
App Widgets
+
Your App Widget will be removed +from the home screen. When external storage is remounted, your App Widget will not be +available for the user to select until the system resets the home application (usually not until a +system reboot).
+
Account Managers
+
Your accounts created with {@link android.accounts.AccountManager} will disappear until +external storage is remounted.
+
Sync Adapters
+
Your {@link android.content.AbstractThreadedSyncAdapter} and all its sync functionality will +not work until external storage is remounted.
+
Device Administrators
+
Your {@link android.app.admin.DeviceAdminReceiver} and all its admin capabilities will +be disabled, which can have unforeseeable consequences for the device functionality, which may +persist after external storage is remounted.
+
+ +

If your application uses any of the features listed above, you should not allow +your application to install on external storage. By default, the system will not allow your +application to install on the external storage, so you don't need to worry about your existing +applications. However, if you're certain that your application should never be installed on the +external storage, then you should make this clear by declaring {@code +android:installLocation} with a value of "{@code internalOnly}". Though this does not +change the default behavior, it explicitly states that your application should only be installed +on the internal storage and serves as a reminder to you and other developers that this decision has +been made.

+ + +

Applications That Should Install on External Storage

+ +

In simple terms, anything that does not use the features listed in the previous section +are safe when installed on external storage. Large games are more commonly the types of +applications that should allow installation on external storage, because games don't typically +provide additional services when innactive. When external storage becomes unavailable and a game +process is killed, there should be no visible effect when the storage becomes available again and +the user restarts the game (assuming that the game properly saved its state during the normal +Activity lifecycle).

+ +

If your application requires several megabytes for the APK file, you should +carefully consider whether to enable the application to install on the external storage so that +users can preserve space on their internal storage.

+ diff --git a/docs/html/guide/guide_toc.cs b/docs/html/guide/guide_toc.cs index 22775017c0826..a484c9fb49fa2 100644 --- a/docs/html/guide/guide_toc.cs +++ b/docs/html/guide/guide_toc.cs @@ -110,7 +110,7 @@
  • Handling Runtime Changes -
    • + new!
  • Localization
    • @@ -431,8 +431,11 @@ Android API Levels
  • - Market Filters - new!
    • + Market Filters + new! +
  • + App Install Location + new!
  • Supported Media Formats
    • diff --git a/docs/html/guide/topics/manifest/manifest-element.jd b/docs/html/guide/topics/manifest/manifest-element.jd index 33537556a3bd8..a35c5a13c29ac 100644 --- a/docs/html/guide/topics/manifest/manifest-element.jd +++ b/docs/html/guide/topics/manifest/manifest-element.jd @@ -161,6 +161,7 @@ this attribute is set to {@code internalOnly}, which is the default setting.

    Introduced in: API Level 8.

    +