176 lines
8.1 KiB
Plaintext
176 lines
8.1 KiB
Plaintext
page.title=Versioning Your Applications
|
|
@jd:body
|
|
|
|
<div id="qv-wrapper">
|
|
<div id="qv">
|
|
|
|
<h2>Quickview</h2>
|
|
|
|
<ul>
|
|
<li>Your application <em>must</em> be versioned</a></li>
|
|
<li>You set the version in the application's manifest file</li>
|
|
<li>How you version your applications affects how users upgrade </li>
|
|
<li>Determine your versioning strategy early in the development process, including considerations for future releases.</li>
|
|
</ul>
|
|
|
|
<h2>In this document</h2>
|
|
|
|
<ol>
|
|
<li><a href="#appversioning">Setting Application Version</a></li>
|
|
<li><a href="#minsdkversion">Specifying Your Application's System API Requirements</a>
|
|
</ol>
|
|
|
|
|
|
<h2>See also</h2>
|
|
|
|
<ol>
|
|
<li><a href="{@docRoot}guide/publishing/preparing.html">Preparing to Publish Your Application</a></li>
|
|
<li><a href="{@docRoot}guide/publishing/publishing.html#market">Publishing On Android Market</a></li>
|
|
<li><a href="{@docRoot}guide/topics/manifest/manifest-intro.html">The AndroidManifest.xml File</a></li>
|
|
</ol>
|
|
|
|
</div>
|
|
</div>
|
|
|
|
<p>Versioning is a critical component of your application upgrade/maintenance
|
|
strategy. </p>
|
|
|
|
<ul>
|
|
<li>Users need to have specific information about the application version that
|
|
is installed on their devices and the upgrade versions available for
|
|
installation. </li>
|
|
<li>Other applications — including other applications that you publish as
|
|
a suite — need to query the system for your application's version, to
|
|
determine compatibility and identify dependencies.</li>
|
|
<li>Services through which you will publish your application(s) may also need to
|
|
query your application for its version, so that they can display the version to
|
|
users. A publishing service may also need to check the application version to
|
|
determine compatibility and establish upgrade/downgrade relationships.</li>
|
|
</ul>
|
|
|
|
<p>The Android system itself <em>does not ever</em> check the application version
|
|
information for an application, such as to enforce restrictions on upgrades,
|
|
compatibility, and so on. Instead, only users or applications themselves are
|
|
responsible for enforcing any version restrictions for applications themselves. </p>
|
|
|
|
<p>The Android system <em>does</em> check any system version compatibility expressed
|
|
by an application in its manifest, in the <code>minSdkVersion</code> attribute. This
|
|
allows an application to specify the minimum system API with which is compatible.
|
|
For more information see <a href="#minsdkversion">Specifying Minimum System API Version</a>.
|
|
|
|
<h2 id="appversioning">Setting Application Version</h2>
|
|
<p>To define the version information for your application, you set attributes in
|
|
the application's manifest file. Two attributes are available, and you should
|
|
always define values for both of them: </p>
|
|
|
|
<ul>
|
|
<li><code>android:versionCode</code> — An integer value that represents
|
|
the version of the application code, relative to other versions.
|
|
|
|
<p>The value is an integer so that other applications can programmatically
|
|
evaluate it, for example to check an upgrade or downgrade relationship. You can
|
|
set the value to any integer you want, however you should make sure that each
|
|
successive release of your application uses a greater value. The system does not
|
|
enforce this behavior, but increasing the value with successive releases is
|
|
normative. </p>
|
|
|
|
<p>Typically, you would release the first version of your application with
|
|
versionCode set to 1, then monotonically increase the value with each release,
|
|
regardless whether the release constitutes a major or minor release. This means
|
|
that the <code>android:versionCode</code> value does not necessarily have a
|
|
strong resemblance to the application release version that is visible to the
|
|
user (see <code>android:versionName</code>, below). Applications and publishing
|
|
services should not display this version value to users.</p>
|
|
</li>
|
|
<li><code>android:versionName</code> — A string value that represents the
|
|
release version of the application code, as it should be shown to users.
|
|
<p>The value is a string so that you can describe the application version as a
|
|
<major>.<minor>.<point> string, or as any other type of
|
|
absolute or relative version identifier. </p>
|
|
|
|
<p>As with <code>android:versionCode</code>, the system does not use this value
|
|
for any internal purpose, other than to enable applications to display it to
|
|
users. Publishing services may also extract the <code>android:versionName</code>
|
|
value for display to users.</p>
|
|
</li>
|
|
</ul>
|
|
|
|
<p>You define both of these version attributes in the
|
|
<code><manifest></code> element of the manifest file. </p>
|
|
|
|
<p>Here's an example manifest that shows the <code>android:versionCode</code>
|
|
and <code>android:versionName</code> attributes in the
|
|
<code><manifest></code> element. </p>
|
|
|
|
<pre>
|
|
<?xml version="1.0" encoding="utf-8"?>
|
|
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
|
|
package="com.example.package.name"
|
|
android:versionCode="2"
|
|
android:versionName="1.1">
|
|
<application android:icon="@drawable/icon" android:label="@string/app_name">
|
|
...
|
|
</application>
|
|
</manifest>
|
|
</pre>
|
|
|
|
<p>In this example, note that <code>android:versionCode</code> value indicates
|
|
that the current .apk contains the second release of the application code, which
|
|
corresponds to a minor follow-on release, as shown by the
|
|
<code>android:versionName</code> string. </p>
|
|
|
|
<p>The Android framework provides an API to let applications query the system
|
|
for version information about your application. To obtain version information,
|
|
applications use the
|
|
{@link android.content.pm.PackageManager#getPackageInfo(java.lang.String, int)}
|
|
method of {@link android.content.pm.PackageManager PackageManager}. </p>
|
|
|
|
<h2 id="minsdkversion">Specifying Your Application's System API Requirements</h2>
|
|
|
|
<p>If your application requires a specific minimum version of the Android
|
|
platform, or is designed only to support a certain range of Android platform
|
|
versions, you can specify those version requirements as API Level identifiers
|
|
in the application's manifest file. Doing so ensures that your
|
|
application can only be installed on devices that
|
|
are running a compatible version of the Android system. </p>
|
|
|
|
<p>To specify API Level requirements, add a <code><uses-sdk></code>
|
|
element in the application's manifest, with one or more of these attributes: </p>
|
|
|
|
<ul>
|
|
<li><code>android:minSdkVersion</code> — The minimum version
|
|
of the Android platform on which the application will run, specified
|
|
by the platform's API Level identifier. </li>
|
|
<li><code>android:targetSdkVersion</code> — Specifies the API Level
|
|
on which the application is designed to run. In some cases, this allows the
|
|
application to use manifest elements or behaviors defined in the target
|
|
API Level, rather than being restricted to using only those defined
|
|
for the minimum API Level.</li>
|
|
<li><code>android:maxSdkVersion</code> — The maximum version
|
|
of the Android platform on which the application is designed to run,
|
|
specified by the platform's API Level identifier. <strong>Important:</strong> Please read the <a
|
|
href="{@docRoot}guide/topics/manifest/uses-sdk-element.html"><code><uses-sdk></code></a>
|
|
documentation before using this attribute. </li>
|
|
</ul>
|
|
|
|
<p>When preparing to install your application, the system checks the value of this
|
|
attribute and compares it to the system version. If the
|
|
<code>android:minSdkVersion</code> value is greater than the system version, the
|
|
system aborts the installation of the application. Similarly, the system
|
|
installs your application only if its <code>android:maxSdkVersion</code>
|
|
is compatible with the platform version.</p>
|
|
|
|
<p>If you do not specify these attributes in your manifest, the system assumes
|
|
that your application is compatible with all platform versions, with no
|
|
maximum API Level. </p>
|
|
|
|
<p>To specify a minimum platform version for your application, add a
|
|
<code><uses-sdk></code> element as a child of
|
|
<code><manifest></code>, then define the
|
|
<code>android:minSdkVersion</code> as an attribute. </p>
|
|
|
|
<p>For more information, see the <a
|
|
href="{@docRoot}guide/topics/manifest/uses-sdk-element.html"><code><uses-sdk></code></a>
|
|
manifest element documentation and the <a
|
|
href="{@docRoot}guide/appendix/api-levels.html">API Levels</a> document.</p>
|