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

  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

  </dd>

  <dt><a name="target"></a>{@code android:targetSdkVersion}</dt>

  <dd>An integer designating the API Level that the application is targetting.

  <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>

  <dd>An integer designating the API Level that the application targets. If not set, the default

value equals that given to {@code minSdkVersion}.

  <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>

  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>

  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>

  <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>