docs: further clarify the behavior of targetSdkVersion
bug: 5854083
Change-Id: I913a245b754604165b4570447f797f7cc66af5f9
diff --git a/docs/html/guide/topics/manifest/uses-sdk-element.jd b/docs/html/guide/topics/manifest/uses-sdk-element.jd
index b371f34..99c91f6 100644
--- a/docs/html/guide/topics/manifest/uses-sdk-element.jd
+++ b/docs/html/guide/topics/manifest/uses-sdk-element.jd
@@ -60,7 +60,7 @@
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 @@
</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—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 @@
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 @@
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 @@
<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>
