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
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
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
will crash during runtime when attempting to access the unavailable APIs. For
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>
<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
older versions (down to {@code minSdkVersion}), but was explicitly tested to
work with the version specified here. Specifying this target version allows the
platform to disable compatibility settings that are not required for the target
version (which may otherwise be turned on in order to maintain
forward-compatibility) or enable newer features that are not available to older
applications. This does not mean that you can program different features for
different versions of the platform&mdash;it simply informs the platform that you
have tested against the target version and the platform should not perform any
extra work to maintain forward-compatibility with the target version.</p>
<p>This attribute informs the system that you have tested against the target version and the
system should not enable any compatibility behaviors to maintain your app's forward-compatibility
with the target version. The application is still able to run on older versions (down to {@code
minSdkVersion}).</p>
<p>As Android evolves with each new version, some behaviors and even appearances might change.
However, if the API level of the platform is higher than the version declared by your app's {@code
targetSdkVersion}, the system may enable compatibility behaviors to ensure that your app
continues to work the way you expect. You can disable such compatibility
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>
</dd>
@@ -89,25 +103,25 @@ href="{@docRoot}guide/appendix/market-filters.html">Market Filters</a>.</p>
designed to run.
<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
<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
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.
<p>To illustrate how this attribute can affect your application after system
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
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
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
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
(5). The system prevents the application from being visible to the user, in
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.
Second, note that in some cases, declaring the attribute can <strong>result in
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
you should consider their effect on your application before setting this
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>
<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
installation or revalidation. Android Market will continue to use the attribute
longer check or enforce the <code>maxSdkVersion</code> attribute during
installation or re-validation. Android Market will continue to use the attribute
as a filter, however, when presenting users with applications available for
download. </div>
</dd>