Android/frameworks_base
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Merge "docs: further clarify the behavior of targetSdkVersion bug: 5854083" into ics-mr1

Browse Source
This commit is contained in:
Scott Main
2012-01-12 11:19:08 -08:00
committed by Android (Google) Code Review
parent 4b1261f17a d4eb682b5f
commit abfe4cb6f0
1 changed files with 35 additions and 21 deletions
Download Patch File Download Diff File Expand all files Collapse all files

56
docs/html/guide/topics/manifest/uses-sdk-element.jd
View File

@@ -60,7 +60,7 @@ href="{@docRoot}guide/appendix/market-filters.html">Market Filters</a>.</p>
attribute, the system assumes a default value of "1", which indicates that your attribute, the system assumes a default value of "1", which indicates that your
application is compatible with all versions of Android. If your application is application is compatible with all versions of Android. If your application is
<em>not</em> compatible with all versions (for instance, it uses APIs introduced <em>not</em> compatible with all versions (for instance, it uses APIs introduced
in API Level 3) and you have not declared the proper <code>android:minSdkVersion</code>, in API Level 3) and you have not declared the proper <code>minSdkVersion</code>,
then when installed on a system with an API Level less than 3, the application then when installed on a system with an API Level less than 3, the application
will crash during runtime when attempting to access the unavailable APIs. For will crash during runtime when attempting to access the unavailable APIs. For
this reason, be certain to declare the appropriate API Level in the this reason, be certain to declare the appropriate API Level in the
@@ -68,18 +68,32 @@ href="{@docRoot}guide/appendix/market-filters.html">Market Filters</a>.</p>
</dd> </dd>
<dt><a name="target"></a>{@code android:targetSdkVersion}</dt> <dt><a name="target"></a>{@code android:targetSdkVersion}</dt>
<dd>An integer designating the API Level that the application is targetting. <dd>An integer designating the API Level that the application targets. If not set, the default
value equals that given to {@code minSdkVersion}.
<p>With this attribute set, the application says that it is able to run on <p>This attribute informs the system that you have tested against the target version and the
older versions (down to {@code minSdkVersion}), but was explicitly tested to system should not enable any compatibility behaviors to maintain your app's forward-compatibility
work with the version specified here. Specifying this target version allows the with the target version. The application is still able to run on older versions (down to {@code
platform to disable compatibility settings that are not required for the target minSdkVersion}).</p>
version (which may otherwise be turned on in order to maintain
forward-compatibility) or enable newer features that are not available to older <p>As Android evolves with each new version, some behaviors and even appearances might change.
applications. This does not mean that you can program different features for However, if the API level of the platform is higher than the version declared by your app's {@code
different versions of the platform&mdash;it simply informs the platform that you targetSdkVersion}, the system may enable compatibility behaviors to ensure that your app
have tested against the target version and the platform should not perform any continues to work the way you expect. You can disable such compatibility
extra work to maintain forward-compatibility with the target version.</p> behaviors by specifying {@code targetSdkVersion} to match the API
level of the platform on which it's running. For example, setting this value to "11" or higher
allows the system to apply a new default theme (Holo) to your app when running on Android 3.0 or
higher and also disables <a href="{@docRoot}guide/practices/screen-compat-mode.html">screen
compatibility mode</a> when running on larger screens (because support for API level 11 implicitly
supports larger screens).</p>
<p>There are many compatibility behaviors that the system may enable based on the value you set
for this attribute. Several of these behaviors are described by the corresponding platform versions
in the {@link android.os.Build.VERSION_CODES} reference.</p>
<p>To maintain your application along with each Android release, you should increase
the value of this attribute to match the latest API level, then thoroughly test your application on
the corresponding platform version.</p>
<p>Introduced in: API Level 4</p> <p>Introduced in: API Level 4</p>
</dd> </dd>
@@ -89,25 +103,25 @@ href="{@docRoot}guide/appendix/market-filters.html">Market Filters</a>.</p>
designed to run. designed to run.
<p>In Android 1.5, 1.6, 2.0, and 2.0.1, the system checks the value of this <p>In Android 1.5, 1.6, 2.0, and 2.0.1, the system checks the value of this
attribute when installing an application and when revalidating the application attribute when installing an application and when re-validating the application
after a system update. In either case, if the application's after a system update. In either case, if the application's
<code>android:maxSdkVersion</code> attribute is lower than the API Level used by <code>maxSdkVersion</code> attribute is lower than the API Level used by
the system itself, then the system will not allow the application to be the system itself, then the system will not allow the application to be
installed. In the case of revalidation after system update, this effectively installed. In the case of re-validation after system update, this effectively
removes your application from the device. removes your application from the device.
<p>To illustrate how this attribute can affect your application after system <p>To illustrate how this attribute can affect your application after system
updates, consider the following example: </p> updates, consider the following example: </p>
<p>An application declaring <code>android:maxSdkVersion="5"</code> in its <p>An application declaring <code>maxSdkVersion="5"</code> in its
manifest is published on Android Market. A user whose device is running Android manifest is published on Android Market. A user whose device is running Android
1.6 (API Level 4) downloads and installs the app. After a few weeks, the user 1.6 (API Level 4) downloads and installs the app. After a few weeks, the user
receives an over-the-air system update to Android 2.0 (API Level 5). After the receives an over-the-air system update to Android 2.0 (API Level 5). After the
update is installed, the system checks the application's update is installed, the system checks the application's
<code>android:maxSdkVersion</code> and successfully revalidates it. The <code>maxSdkVersion</code> and successfully re-validates it. The
application functions as normal. However, some time later, the device receives application functions as normal. However, some time later, the device receives
another system update, this time to Android 2.0.1 (API Level 6). After the another system update, this time to Android 2.0.1 (API Level 6). After the
update, the system can no longer revalidate the application because the system's update, the system can no longer re-validate the application because the system's
own API Level (6) is now higher than the maximum supported by the application own API Level (6) is now higher than the maximum supported by the application
(5). The system prevents the application from being visible to the user, in (5). The system prevents the application from being visible to the user, in
effect removing it from the device.</p> effect removing it from the device.</p>
@@ -120,7 +134,7 @@ href="{@docRoot}guide/appendix/market-filters.html">Market Filters</a>.</p>
provided it uses only standard APIs and follows development best practices. provided it uses only standard APIs and follows development best practices.
Second, note that in some cases, declaring the attribute can <strong>result in Second, note that in some cases, declaring the attribute can <strong>result in
your application being removed from users' devices after a system your application being removed from users' devices after a system
update</strong> to a higher API Level. Most devices on which your appplication update</strong> to a higher API Level. Most devices on which your application
is likely to be installed will receive periodic system updates over the air, so is likely to be installed will receive periodic system updates over the air, so
you should consider their effect on your application before setting this you should consider their effect on your application before setting this
attribute.</p> attribute.</p>
@@ -128,8 +142,8 @@ href="{@docRoot}guide/appendix/market-filters.html">Market Filters</a>.</p>
<p style="margin-bottom:1em;">Introduced in: API Level 4</p> <p style="margin-bottom:1em;">Introduced in: API Level 4</p>
<div class="special">Future versions of Android (beyond Android 2.0.1) will no <div class="special">Future versions of Android (beyond Android 2.0.1) will no
longer check or enforce the <code>android:maxSdkVersion</code> attribute during longer check or enforce the <code>maxSdkVersion</code> attribute during
installation or revalidation. Android Market will continue to use the attribute installation or re-validation. Android Market will continue to use the attribute
as a filter, however, when presenting users with applications available for as a filter, however, when presenting users with applications available for
download. </div> download. </div>
</dd> </dd>