The Android Open Source Project | 9066cfe | 2009-03-03 19:31:44 -0800 | [diff] [blame] | 1 | page.title=<manifest> |
Scott Main | 2a1b706 | 2011-02-22 14:43:41 -0800 | [diff] [blame] | 2 | parent.title=The AndroidManifest.xml File |
| 3 | parent.link=manifest-intro.html |
The Android Open Source Project | 9066cfe | 2009-03-03 19:31:44 -0800 | [diff] [blame] | 4 | @jd:body |
| 5 | |
| 6 | <dl class="xml"> |
| 7 | <dt>syntax:</dt> |
| 8 | <dd><pre class="stx"><manifest xmlns:<a href="#nspace">android</a>="http://schemas.android.com/apk/res/android" |
| 9 | <a href="#package">package</a>="<i>string</i>" |
| 10 | android:<a href="#uid">sharedUserId</a>="<i>string</i>" |
Dirk Dougherty | 9c3209d | 2009-04-18 22:01:18 -0700 | [diff] [blame] | 11 | android:<a href="#uidlabel">sharedUserLabel</a>="<i>string resource</i>" <!-- ##api level 3## --> |
The Android Open Source Project | 9066cfe | 2009-03-03 19:31:44 -0800 | [diff] [blame] | 12 | android:<a href="#vcode">versionCode</a>="<i>integer</i>" |
Scott Main | c861a5d | 2010-04-05 15:47:54 -0700 | [diff] [blame] | 13 | android:<a href="#vname">versionName</a>="<i>string</i>" |
| 14 | android:<a href="#install">installLocation</a>=["auto" | "internalOnly" | "preferExternal"] > |
The Android Open Source Project | 9066cfe | 2009-03-03 19:31:44 -0800 | [diff] [blame] | 15 | . . . |
| 16 | </manifest></pre></dd> |
| 17 | |
| 18 | <p> |
| 19 | <dt>contained in:</dt> |
| 20 | <dd><i>none</i></dd> |
| 21 | |
| 22 | <p> |
| 23 | <p> |
| 24 | <dt>must contain:</dt> |
| 25 | <dd><code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code></dd> |
| 26 | |
| 27 | <dt>can contain:</dt> |
| 28 | <dd><code><a href="{@docRoot}guide/topics/manifest/instrumentation-element.html"><instrumentation></a></code> |
| 29 | <br/><code><a href="{@docRoot}guide/topics/manifest/permission-element.html"><permission></a></code> |
| 30 | <br/><code><a href="{@docRoot}guide/topics/manifest/permission-group-element.html"><permission-group></a></code> |
| 31 | <br/><code><a href="{@docRoot}guide/topics/manifest/permission-tree-element.html"><permission-tree></a></code> |
Dirk Dougherty | 9c3209d | 2009-04-18 22:01:18 -0700 | [diff] [blame] | 32 | <br/><code><a href="{@docRoot}guide/topics/manifest/uses-configuration-element.html"><uses-configuration></a></code> <!-- ##api level 3## --> |
| 33 | <br/><code><a href="{@docRoot}guide/topics/manifest/uses-permission-element.html"><uses-permission></a></code></dd> |
Scott Main | 74577f7 | 2009-04-18 16:13:35 -0700 | [diff] [blame] | 34 | <br/><code><a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html"><uses-sdk></a></code></dd> |
The Android Open Source Project | 9066cfe | 2009-03-03 19:31:44 -0800 | [diff] [blame] | 35 | |
| 36 | <p> |
| 37 | <dt>description:</dt> |
| 38 | <dd>The root element of the AndroidManifest.xml file. It must |
| 39 | contain an <code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> element |
| 40 | and specify {@code xlmns:android} and {@code package} attributes.</dd> |
| 41 | |
| 42 | <dt>attributes:</dt> |
Scott Main | c861a5d | 2010-04-05 15:47:54 -0700 | [diff] [blame] | 43 | <dd> |
| 44 | <dl class="attr"> |
The Android Open Source Project | 9066cfe | 2009-03-03 19:31:44 -0800 | [diff] [blame] | 45 | <dt><a name="nspace"></a>{@code xmlns:android}</dt> |
| 46 | <dd>Defines the Android namespace. This attribute should always be set |
| 47 | to "{@code http://schemas.android.com/apk/res/android}".</dd> |
| 48 | |
| 49 | <dt><a name="package"></a>{@code package}</dt> |
Scott Main | 9fc3579 | 2011-06-20 16:36:28 -0700 | [diff] [blame] | 50 | <dd>A full Java-language-style package name for the application. The name should |
Kenny Root | e271820 | 2009-06-09 13:42:54 -0500 | [diff] [blame] | 51 | be unique. The name may contain uppercase or lowercase letters ('A' |
| 52 | through 'Z'), numbers, and underscores ('_'). However, individual |
Scott Main | 9fc3579 | 2011-06-20 16:36:28 -0700 | [diff] [blame] | 53 | package name parts may only start with letters. |
| 54 | |
| 55 | <p>To avoid conflicts with other developers, you should use Internet domain ownership as the |
| 56 | basis for your package names (in reverse). For example, applications published by Google start with |
| 57 | <code>com.google</code>. You should also never use the <code>com.example</code> namespace when |
| 58 | publishing your applications.</p> |
The Android Open Source Project | 9066cfe | 2009-03-03 19:31:44 -0800 | [diff] [blame] | 59 | |
Scott Main | c861a5d | 2010-04-05 15:47:54 -0700 | [diff] [blame] | 60 | <p> |
| 61 | The package name serves as a unique identifier for the application. |
| 62 | It's also the default name for the application process (see the |
| 63 | <code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> |
| 64 | element's |
| 65 | <code><a href="{@docRoot}guide/topics/manifest/application-element.html#aff">process</a></code> |
| 66 | process</a></code> attribute) and the default task affinity of an activity |
| 67 | (see the |
| 68 | <code><a href="{@docRoot}guide/topics/manifest/activity-element.html"><activity></a></code> |
| 69 | element's |
| 70 | <code><a href="{@docRoot}guide/topics/manifest/activity-element.html#aff">taskAffinity</a></code> attribute). |
| 71 | </p> |
Scott Main | 9fc3579 | 2011-06-20 16:36:28 -0700 | [diff] [blame] | 72 | |
| 73 | <p class="caution"><strong>Caution:</strong> Once you publish your application, you |
| 74 | <strong>cannot change the package name</strong>. The package name defines your application's |
| 75 | identity, so if you change it, then it is considered to be a different application and users of |
| 76 | the previous version cannot update to the new version.</p> |
| 77 | |
Scott Main | c861a5d | 2010-04-05 15:47:54 -0700 | [diff] [blame] | 78 | </dd> |
The Android Open Source Project | 9066cfe | 2009-03-03 19:31:44 -0800 | [diff] [blame] | 79 | |
| 80 | <dt><a name="uid"></a>{@code android:sharedUserId}</dt> |
| 81 | <dd>The name of a Linux user ID that will be shared with other applications. |
| 82 | By default, Android assigns each application its own unique user ID. |
| 83 | However, if this attribute is set to the same value for two or more applications, |
| 84 | they will all share the same ID — provided that they are also signed |
| 85 | by the same certificate. Application with the same user ID can access each |
Dirk Dougherty | 9c3209d | 2009-04-18 22:01:18 -0700 | [diff] [blame] | 86 | other's data and, if desired, run in the same process.</dd> |
| 87 | |
| 88 | <dt><a name="uidlabel"></a>{@code android:sharedUserLabel}</dt> |
| 89 | <dd>A user-readable label for the shared user ID. The label must be set as |
| 90 | a reference to a string resource; it cannot be a raw string. |
| 91 | |
Scott Main | c861a5d | 2010-04-05 15:47:54 -0700 | [diff] [blame] | 92 | <p> |
| 93 | <!-- ##api level indication## --> |
| 94 | This attribute was introduced in API Level 3. It is meaningful only if the |
| 95 | <code><a href="#uid">sharedUserId</a></code> attribute is also set. |
| 96 | </p> |
| 97 | </dd> |
The Android Open Source Project | 9066cfe | 2009-03-03 19:31:44 -0800 | [diff] [blame] | 98 | |
| 99 | <dt><a name="vcode"></a>{@code android:versionCode}</dt> |
Scott Main | c861a5d | 2010-04-05 15:47:54 -0700 | [diff] [blame] | 100 | <dd>An internal version number. This number is used only to determine whether |
The Android Open Source Project | 9066cfe | 2009-03-03 19:31:44 -0800 | [diff] [blame] | 101 | one version is more recent than another, with higher numbers indicating more |
| 102 | recent versions. This is not the version number shown to users; that number |
| 103 | is set by the {@code versionName} attribute. |
| 104 | |
Scott Main | c861a5d | 2010-04-05 15:47:54 -0700 | [diff] [blame] | 105 | <p> |
| 106 | The value must be set as an integer, such as "100". You can define it however |
| 107 | you want, as long as each successive version has a higher number. For example, |
| 108 | it could be a build number. Or you could translate a version number in "x.y" |
| 109 | format to an integer by encoding the "x" and "y" separately in the lower and |
| 110 | upper 16 bits. Or you could simply increase the number by one each time a new |
| 111 | version is released. |
| 112 | </p> |
| 113 | </dd> |
The Android Open Source Project | 9066cfe | 2009-03-03 19:31:44 -0800 | [diff] [blame] | 114 | |
| 115 | <dt><a name="vname"></a>{@code android:versionName}</dt> |
| 116 | <dd>The version number shown to users. This attribute can be set as a raw |
| 117 | string or as a reference to a string resource. The string has no other purpose |
| 118 | than to be displayed to users. The {@code versionCode} attribute holds |
| 119 | the significant version number used internally. |
Scott Main | c861a5d | 2010-04-05 15:47:54 -0700 | [diff] [blame] | 120 | </dd> |
| 121 | |
| 122 | <dt><a name="install"></a>{@code android:installLocation}</dt> |
Scott Main | 76aafa4 | 2010-04-05 17:59:38 -0700 | [diff] [blame] | 123 | <dd>The default install location for the application. |
Scott Main | c861a5d | 2010-04-05 15:47:54 -0700 | [diff] [blame] | 124 | |
| 125 | <p>The following keyword strings are accepted:</p> |
| 126 | |
| 127 | <table> |
| 128 | <tr> |
| 129 | <th>Value</th> |
| 130 | <th>Description</th> |
| 131 | </tr><tr> |
Scott Main | c861a5d | 2010-04-05 15:47:54 -0700 | [diff] [blame] | 132 | <td>"{@code internalOnly}"</td> |
Scott Main | c4c42ee | 2010-05-07 15:30:15 -0700 | [diff] [blame] | 133 | <td>The application must be installed on the internal device storage only. If this is set, |
| 134 | the application will never be installed on the external storage. If the internal |
| 135 | storage is full, then the system will not install the application. This is also the default behavior |
| 136 | if you do not define {@code android:installLocation}.</td> |
| 137 | </tr><tr> |
| 138 | <td>"{@code auto}"</td> |
| 139 | <td>The application may be installed on the external storage, but the system will install the |
| 140 | application on the internal storage by default. If the internal storage is full, then the system |
| 141 | will install it on the external storage. Once installed, the user can move the application |
| 142 | to either internal or external storage through the system settings.</td> |
Scott Main | c861a5d | 2010-04-05 15:47:54 -0700 | [diff] [blame] | 143 | </tr><tr> |
| 144 | <td>"{@code preferExternal}"</td> |
Scott Main | 76aafa4 | 2010-04-05 17:59:38 -0700 | [diff] [blame] | 145 | <td>The application prefers to be installed on the external storage (SD card). There is no |
| 146 | guarantee that the system will honor this request. The application might be installed on internal |
| 147 | storage if the external media is unavailable or full, or if the application uses the forward-locking |
Scott Main | c4c42ee | 2010-05-07 15:30:15 -0700 | [diff] [blame] | 148 | mechanism (not supported on external storage). Once installed, the user can move the application to |
| 149 | either internal or external storage through the system settings.</td> |
Scott Main | c861a5d | 2010-04-05 15:47:54 -0700 | [diff] [blame] | 150 | </tr> |
| 151 | </table> |
| 152 | |
Dirk Dougherty | 4d7bc655 | 2012-01-27 17:56:49 -0800 | [diff] [blame] | 153 | <p class="caution"><strong>Caution:</strong> If your application uses Google Play's Copy |
| 154 | Protection feature, it cannot be installed to a device's SD card. However, if you use Google |
| 155 | Play's <a href="{@docRoot}guide/market/licensing.html">Application Licensing</a> instead, |
Joe Fernandez | f6d8de6 | 2011-05-12 10:00:25 -0700 | [diff] [blame] | 156 | your application <em>can</em> be installed to internal or external storage, including SD cards.</p> |
| 157 | |
Scott Main | c4c42ee | 2010-05-07 15:30:15 -0700 | [diff] [blame] | 158 | <p class="note"><strong>Note:</strong> By default, your application will be installed on the |
Joe Fernandez | f6d8de6 | 2011-05-12 10:00:25 -0700 | [diff] [blame] | 159 | internal storage and cannot be installed on the external storage unless you define this attribute |
| 160 | to be either "{@code auto}" or "{@code preferExternal}".</p> |
Scott Main | c4c42ee | 2010-05-07 15:30:15 -0700 | [diff] [blame] | 161 | |
Scott Main | c861a5d | 2010-04-05 15:47:54 -0700 | [diff] [blame] | 162 | <p>When an application is installed on the external storage:</p> |
| 163 | <ul> |
| 164 | <li>The {@code .apk} file is saved |
| 165 | to the external storage, but any application data (such as databases) is still saved on |
| 166 | the internal device memory.</li> |
| 167 | <li>The container in which the {@code .apk} file is saved is encrypted with a key that allows |
| 168 | the application to operate only on the device that installed it. (A user cannot |
| 169 | transfer the SD card to another device and use applications installed on the card.) Though, |
| 170 | multiple SD cards can be used with the same device.</li> |
| 171 | <li>At the user's request, the application can be moved to the internal storage.</li> |
| 172 | </ul> |
| 173 | |
| 174 | <p>The user may also request to move an application from the internal storage to the external |
Scott Main | 76aafa4 | 2010-04-05 17:59:38 -0700 | [diff] [blame] | 175 | storage. However, the system will not allow the user to move the application to external storage if |
Scott Main | c4c42ee | 2010-05-07 15:30:15 -0700 | [diff] [blame] | 176 | this attribute is set to {@code internalOnly}, which is the default setting.</p> |
| 177 | |
Scott Main | 2cbe92e | 2010-11-17 18:14:58 -0800 | [diff] [blame] | 178 | <p>Read <a href="{@docRoot}guide/appendix/install-location.html">App Install Location</a> for |
| 179 | more information about using this attribute (including how to maintain backward compatibility).</p> |
| 180 | |
Scott Main | c4c42ee | 2010-05-07 15:30:15 -0700 | [diff] [blame] | 181 | <p>Introduced in: API Level 8.</p> |
Scott Main | c861a5d | 2010-04-05 15:47:54 -0700 | [diff] [blame] | 182 | |
Scott Main | 5cdf5fd | 2010-05-11 14:21:53 -0700 | [diff] [blame] | 183 | |
Scott Main | c861a5d | 2010-04-05 15:47:54 -0700 | [diff] [blame] | 184 | </dd> |
| 185 | |
| 186 | </dl> |
| 187 | </dd><!-- end attributes --> |
The Android Open Source Project | 9066cfe | 2009-03-03 19:31:44 -0800 | [diff] [blame] | 188 | |
Dirk Dougherty | 9c3209d | 2009-04-18 22:01:18 -0700 | [diff] [blame] | 189 | <!-- ##api level indication## --> |
| 190 | <dt>introduced in:</dt> |
Scott Main | 76aafa4 | 2010-04-05 17:59:38 -0700 | [diff] [blame] | 191 | <dd>API Level 1 for all attributes, unless noted otherwise in the attribute description.</dd> |
Dirk Dougherty | 9c3209d | 2009-04-18 22:01:18 -0700 | [diff] [blame] | 192 | |
The Android Open Source Project | 9066cfe | 2009-03-03 19:31:44 -0800 | [diff] [blame] | 193 | <p> |
| 194 | <dt>see also:</dt> |
Scott Main | 2cbe92e | 2010-11-17 18:14:58 -0800 | [diff] [blame] | 195 | <dd> |
Scott Main | c4c42ee | 2010-05-07 15:30:15 -0700 | [diff] [blame] | 196 | <code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code></dd> |
The Android Open Source Project | 9066cfe | 2009-03-03 19:31:44 -0800 | [diff] [blame] | 197 | |
| 198 | </dl> |