1 page.title=The AndroidManifest.xml File 2 @jd:body 3 4 <div id="qv-wrapper"> 5 <div id="qv"> 6 7 <h2>In this document</h2> 8 <ol> 9 <li><a href="#filestruct">Structure of the Manifest File</a></li> 10 <li><a href="#filec">File Conventions</a> 11 <li><a href="#filef">File Features</a> 12 <ol> 13 <li><a href="#ifs">Intent Filters</a></li> 14 <li><a href="#iconlabel">Icons and Labels</a></li> 15 <li><a href="#perms">Permissions</a></li> 16 <li><a href="#libs">Libraries</a></li> 17 </ol></li> 18 </ol> 19 </div> 20 </div> 21 22 <p> 23 Every application must have an AndroidManifest.xml file (with precisely that 24 name) in its root directory. The manifest presents essential information about 25 the application to the Android system, information the system must have before 26 it can run any of the application's code. Among other things, the manifest 27 does the following: 28 </p> 29 30 <ul> 31 <li>It names the Java package for the application. 32 The package name serves as a unique identifier for the application.</li> 33 34 <li>It describes the components of the application — the activities, 35 services, broadcast receivers, and content providers that the application is 36 composed of. It names the classes that implement each of the components and 37 publishes their capabilities (for example, which {@link android.content.Intent 38 Intent} messages they can handle). These declarations let the Android system 39 know what the components are and under what conditions they can be launched.</li> 40 41 <li>It determines which processes will host application components.</li> 42 43 <li>It declares which permissions the application must have in order to 44 access protected parts of the API and interact with other applications.</li> 45 46 <li>It also declares the permissions that others are required to have in 47 order to interact with the application's components.</li> 48 49 <li>It lists the {@link android.app.Instrumentation} classes that provide 50 profiling and other information as the application is running. These declarations 51 are present in the manifest only while the application is being developed and 52 tested; they're removed before the application is published.</li> 53 54 <li>It declares the minimum level of the Android API that the application 55 requires.</li> 56 57 <li>It lists the libraries that the application must be linked against.</li> 58 </ul> 59 60 61 <h2 id="filestruct">Structure of the Manifest File</h2> 62 63 <p> 64 The diagram below shows the general structure of the manifest file and 65 every element that it can contain. Each element, along with all of its 66 attributes, is documented in full in a separate file. To view detailed 67 information about any element, click on the element name in the diagram, 68 in the alphabetical list of elements that follows the diagram, or on any 69 other mention of the element name. 70 </p> 71 72 <pre> 73 <?xml version="1.0" encoding="utf-8"?> 74 75 <a href="{@docRoot}guide/topics/manifest/manifest-element.html"><manifest></a> 76 77 <a href="{@docRoot}guide/topics/manifest/uses-permission-element.html"><uses-permission /></a> 78 <a href="{@docRoot}guide/topics/manifest/permission-element.html"><permission /></a> 79 <a href="{@docRoot}guide/topics/manifest/permission-tree-element.html"><permission-tree /></a> 80 <a href="{@docRoot}guide/topics/manifest/permission-group-element.html"><permission-group /></a> 81 <a href="{@docRoot}guide/topics/manifest/instrumentation-element.html"><instrumentation /></a> 82 <a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html"><uses-sdk /></a> 83 <a href="{@docRoot}guide/topics/manifest/uses-configuration-element.html"><uses-configuration /></a> <!-- ##api level 3## --> 84 <a href="{@docRoot}guide/topics/manifest/uses-feature-element.html"><uses-feature /></a> <!-- ##api level 4## --> 85 <a href="{@docRoot}guide/topics/manifest/supports-screens-element.html"><supports-screens /></a> <!-- ##api level 4## --> 86 <a href="{@docRoot}guide/topics/manifest/compatible-screens-element.html"><compatible-screens /></a> <!-- ##api level 9## --> 87 <a href="{@docRoot}guide/topics/manifest/supports-gl-texture-element.html"><supports-gl-texture /></a> <!-- ##api level 11## --> 88 89 <a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a> 90 91 <a href="{@docRoot}guide/topics/manifest/activity-element.html"><activity></a> 92 <a href="{@docRoot}guide/topics/manifest/intent-filter-element.html"><intent-filter></a> 93 <a href="{@docRoot}guide/topics/manifest/action-element.html"><action /></a> 94 <a href="{@docRoot}guide/topics/manifest/category-element.html"><category /></a> 95 <a href="{@docRoot}guide/topics/manifest/data-element.html"><data /></a> 96 <a href="{@docRoot}guide/topics/manifest/intent-filter-element.html"></intent-filter></a> 97 <a href="{@docRoot}guide/topics/manifest/meta-data-element.html"><meta-data /></a> 98 <a href="{@docRoot}guide/topics/manifest/activity-element.html"></activity></a> 99 100 <a href="{@docRoot}guide/topics/manifest/activity-alias-element.html"><activity-alias></a> 101 <a href="{@docRoot}guide/topics/manifest/intent-filter-element.html"><intent-filter></a> . . . <a href="{@docRoot}guide/topics/manifest/intent-filter-element.html"></intent-filter></a> 102 <a href="{@docRoot}guide/topics/manifest/meta-data-element.html"><meta-data /></a> 103 <a href="{@docRoot}guide/topics/manifest/activity-alias-element.html"></activity-alias></a> 104 105 <a href="{@docRoot}guide/topics/manifest/service-element.html"><service></a> 106 <a href="{@docRoot}guide/topics/manifest/intent-filter-element.html"><intent-filter></a> . . . <a href="{@docRoot}guide/topics/manifest/intent-filter-element.html"></intent-filter></a> 107 <a href="{@docRoot}guide/topics/manifest/meta-data-element.html"><meta-data/></a> 108 <a href="{@docRoot}guide/topics/manifest/service-element.html"></service></a> 109 110 <a href="{@docRoot}guide/topics/manifest/receiver-element.html"><receiver></a> 111 <a href="{@docRoot}guide/topics/manifest/intent-filter-element.html"><intent-filter></a> . . . <a href="{@docRoot}guide/topics/manifest/intent-filter-element.html"></intent-filter></a> 112 <a href="{@docRoot}guide/topics/manifest/meta-data-element.html"><meta-data /></a> 113 <a href="{@docRoot}guide/topics/manifest/receiver-element.html"></receiver></a> 114 115 <a href="{@docRoot}guide/topics/manifest/provider-element.html"><provider></a> 116 <a href="{@docRoot}guide/topics/manifest/grant-uri-permission-element.html"><grant-uri-permission /></a> 117 <a href="{@docRoot}guide/topics/manifest/meta-data-element.html"><meta-data /></a> 118 <a href="{@docRoot}guide/topics/manifest/path-permission-element.html"><path-permission /></a> 119 <a href="{@docRoot}guide/topics/manifest/provider-element.html"></provider></a> 120 121 <a href="{@docRoot}guide/topics/manifest/uses-library-element.html"><uses-library /></a> 122 123 <a href="{@docRoot}guide/topics/manifest/application-element.html"></application></a> 124 125 <a href="{@docRoot}guide/topics/manifest/manifest-element.html"></manifest></a> 126 </pre> 127 128 <p> 129 All the elements that can appear in the manifest file are listed below 130 in alphabetical order. These are the only legal elements; you cannot 131 add your own elements or attributes. 132 </p> 133 134 <p style="margin-left: 2em"> 135 <code><a href="{@docRoot}guide/topics/manifest/action-element.html"><action></a></code> 136 <br/><code><a href="{@docRoot}guide/topics/manifest/activity-element.html"><activity></a></code> 137 <br/><code><a href="{@docRoot}guide/topics/manifest/activity-alias-element.html"><activity-alias></a></code> 138 <br/><code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> 139 <br/><code><a href="{@docRoot}guide/topics/manifest/category-element.html"><category></a></code> 140 <br/><code><a href="{@docRoot}guide/topics/manifest/data-element.html"><data></a></code> 141 <br/><code><a href="{@docRoot}guide/topics/manifest/grant-uri-permission-element.html"><grant-uri-permission></a></code> 142 <br/><code><a href="{@docRoot}guide/topics/manifest/instrumentation-element.html"><instrumentation></a></code> 143 <br/><code><a href="{@docRoot}guide/topics/manifest/intent-filter-element.html"><intent-filter></a></code> 144 <br/><code><a href="{@docRoot}guide/topics/manifest/manifest-element.html"><manifest></a></code> 145 <br/><code><a href="{@docRoot}guide/topics/manifest/meta-data-element.html"><meta-data></a></code> 146 <br/><code><a href="{@docRoot}guide/topics/manifest/permission-element.html"><permission></a></code> 147 <br/><code><a href="{@docRoot}guide/topics/manifest/permission-group-element.html"><permission-group></a></code> 148 <br/><code><a href="{@docRoot}guide/topics/manifest/permission-tree-element.html"><permission-tree></a></code> 149 <br/><code><a href="{@docRoot}guide/topics/manifest/provider-element.html"><provider></a></code> 150 <br/><code><a href="{@docRoot}guide/topics/manifest/receiver-element.html"><receiver></a></code> 151 <br/><code><a href="{@docRoot}guide/topics/manifest/service-element.html"><service></a></code> 152 <br/><code><a href="{@docRoot}guide/topics/manifest/supports-screens-element.html"><supports-screens></a></code> <!-- ##api level 4## --> 153 <br/><code><a href="{@docRoot}guide/topics/manifest/uses-configuration-element.html"><uses-configuration></a></code> <!-- ##api level 3## --> 154 <br/><code><a href="{@docRoot}guide/topics/manifest/uses-feature-element.html"><uses-feature></a></code> <!-- ##api level 4## --> 155 <br/><code><a href="{@docRoot}guide/topics/manifest/uses-library-element.html"><uses-library></a></code> 156 <br/><code><a href="{@docRoot}guide/topics/manifest/uses-permission-element.html"><uses-permission></a></code> 157 <br/><code><a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html"><uses-sdk></a></code> 158 </p> 159 160 161 162 163 <h2 id="filec">File Conventions</h2> 164 165 <p> 166 Some conventions and rules apply generally to all elements and attributes 167 in the manifest: 168 </p> 169 170 <dl> 171 <dt><b>Elements</b></dt> 172 <dd>Only the 173 <code><a href="{@docRoot}guide/topics/manifest/manifest-element.html"><manifest></a></code> and 174 <code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> 175 elements are required, they each must be present and can occur only once. 176 Most of the others can occur many times or not at all — although at 177 least some of them must be present for the manifest to accomplish anything 178 meaningful. 179 180 <p> 181 If an element contains anything at all, it contains other elements. 182 All values are set through attributes, not as character data within an element. 183 </p> 184 185 <p> 186 Elements at the same level are generally not ordered. For example, 187 <code><a href="{@docRoot}guide/topics/manifest/activity-element.html"><activity></a></code>, 188 <code><a href="{@docRoot}guide/topics/manifest/provider-element.html"><provider></a></code>, and 189 <code><a href="{@docRoot}guide/topics/manifest/service-element.html"><service></a></code> 190 elements can be intermixed in any sequence. (An 191 <code><a href="{@docRoot}guide/topics/manifest/activity-alias-element.html"><activity-alias></a></code> 192 element is the exception to this rule: It must follow the 193 <code><a href="{@docRoot}guide/topics/manifest/activity-element.html"><activity></a></code> 194 it is an alias for.) 195 </p></dd> 196 197 <dt><b>Attributes</b></dt> 198 <dd>In a formal sense, all attributes are optional. However, there are some 199 that must be specified for an element to accomplish its purpose. Use the 200 documentation as a guide. For truly optional attributes, it mentions a default 201 value or states what happens in the absence of a specification. 202 203 <p>Except for some attributes of the root 204 <code><a href="{@docRoot}guide/topics/manifest/manifest-element.html"><manifest></a></code> 205 element, all attribute names begin with an {@code android:} prefix — 206 for example, {@code android:alwaysRetainTaskState}. Because the prefix is 207 universal, the documentation generally omits it when referring to attributes 208 by name.</p></dd> 209 210 <dt><b>Declaring class names</b></dt> 211 <dd>Many elements correspond to Java objects, including elements for the 212 application itself (the 213 <code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> 214 element) and its principal components — activities 215 (<code><a href="{@docRoot}guide/topics/manifest/activity-element.html"><activity></a></code>), 216 services 217 (<code><a href="{@docRoot}guide/topics/manifest/service-element.html"><service></a></code>), 218 broadcast receivers 219 (<code><a href="{@docRoot}guide/topics/manifest/receiver-element.html"><receiver></a></code>), 220 and content providers 221 (<code><a href="{@docRoot}guide/topics/manifest/provider-element.html"><provider></a></code>). 222 223 <p> 224 If you define a subclass, as you almost always would for the component classes 225 ({@link android.app.Activity}, {@link android.app.Service}, 226 {@link android.content.BroadcastReceiver}, and {@link android.content.ContentProvider}), 227 the subclass is declared through a {@code name} attribute. The name must include 228 the full package designation. 229 For example, an {@link android.app.Service} subclass might be declared as follows: 230 </p> 231 232 <pre><manifest . . . > 233 <application . . . > 234 <service android:name="com.example.project.SecretService" . . . > 235 . . . 236 </service> 237 . . . 238 </application> 239 </manifest></pre> 240 241 <p> 242 However, as a shorthand, if the first character of the string is a period, the 243 string is appended to the application's package name (as specified by the 244 <code><a href="{@docRoot}guide/topics/manifest/manifest-element.html"><manifest></a></code> 245 element's 246 <code><a href="{@docRoot}guide/topics/manifest/manifest-element.html#package">package</a></code> 247 attribute). The following assignment is the same as the one above: 248 </p> 249 250 <pre><manifest package="com.example.project" . . . > 251 <application . . . > 252 <service android:name=".SecretService" . . . > 253 . . . 254 </service> 255 . . . 256 </application> 257 </manifest></pre> 258 259 <p> 260 When starting a component, Android creates an instance of the named subclass. 261 If a subclass isn't specified, it creates an instance of the base class. 262 </p></dd> 263 264 <dt><b>Multiple values</b></dt> 265 <dd>If more than one value can be specified, the element is almost always 266 repeated, rather than listing multiple values within a single element. 267 For example, an intent filter can list several actions: 268 269 <pre><intent-filter . . . > 270 <action android:name="android.intent.action.EDIT" /> 271 <action android:name="android.intent.action.INSERT" /> 272 <action android:name="android.intent.action.DELETE" /> 273 . . . 274 </intent-filter></pre></dd> 275 276 <dt><b>Resource values</b></dt> 277 <dd>Some attributes have values that can be displayed to users — for 278 example, a label and an icon for an activity. The values of these attributes 279 should be localized and therefore set from a resource or theme. Resource 280 values are expressed in the following format,</p> 281 282 <p style="margin-left: 2em">{@code @[<i>package</i>:]<i>type</i>:<i>name</i>}</p> 283 284 <p> 285 where the <i>package</i> name can be omitted if the resource is in the same package 286 as the application, <i>type</i> is a type of resource — such as "string" or 287 "drawable" — and <i>name</i> is the name that identifies the specific resource. 288 For example: 289 </p> 290 291 <pre><activity android:icon="@drawable/smallPic" . . . ></pre> 292 293 <p> 294 Values from a theme are expressed in a similar manner, but with an initial '{@code ?}' 295 rather than '{@code @}': 296 </p> 297 298 <p style="margin-left: 2em">{@code ?[<i>package</i>:]<i>type</i>:<i>name</i>} 299 </p></dd> 300 301 <dt><b>String values</b></dt> 302 <dd>Where an attribute value is a string, double backslashes ('{@code \\}') 303 must be used to escape characters — for example, '{@code \\n}' for 304 a newline or '{@code \\uxxxx}' for a Unicode character.</dd> 305 </dl> 306 307 308 <h2 id="filef">File Features</h2> 309 310 <p> 311 The following sections describe how some Android features are reflected 312 in the manifest file. 313 </p> 314 315 316 <h3 id="ifs">Intent Filters</h3> 317 318 <p> 319 The core components of an application (its activities, services, and broadcast 320 receivers) are activated by <i>intents</i>. An intent is a 321 bundle of information (an {@link android.content.Intent} object) describing a 322 desired action — including the data to be acted upon, the category of 323 component that should perform the action, and other pertinent instructions. 324 Android locates an appropriate component to respond to the intent, launches 325 a new instance of the component if one is needed, and passes it the 326 Intent object. 327 </p> 328 329 <p> 330 Components advertise their capabilities — the kinds of intents they can 331 respond to — through <i>intent filters</i>. Since the Android system 332 must learn which intents a component can handle before it launches the component, 333 intent filters are specified in the manifest as 334 <code><a href="{@docRoot}guide/topics/manifest/intent-filter-element.html"><intent-filter></a></code> 335 elements. A component may have any number of filters, each one describing 336 a different capability. 337 </p> 338 339 <p> 340 An intent that explicitly names a target component will activate that component; 341 the filter doesn't play a role. But an intent that doesn't specify a target by 342 name can activate a component only if it can pass through one of the component's 343 filters. 344 </p> 345 346 <p> 347 For information on how Intent objects are tested against intent filters, 348 see a separate document, 349 <a href="{@docRoot}guide/components/intents-filters.html">Intents 350 and Intent Filters</a>. 351 </p> 352 353 354 <h3 id="iconlabel">Icons and Labels</h3> 355 356 <p> 357 A number of elements have {@code icon} and {@code label} attributes for a 358 small icon and a text label that can be displayed to users. Some also have a 359 {@code description} attribute for longer explanatory text that can also be 360 shown on-screen. For example, the 361 <code><a href="{@docRoot}guide/topics/manifest/permission-element.html"><permission></a></code> 362 element has all three of these attributes, so that when the user is asked whether 363 to grant the permission to an application that has requested it, an icon representing 364 the permission, the name of the permission, and a description of what it 365 entails can all be presented to the user. 366 </p> 367 368 <p> 369 In every case, the icon and label set in a containing element become the default 370 {@code icon} and {@code label} settings for all of the container's subelements. 371 Thus, the icon and label set in the 372 <code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> 373 element are the default icon and label for each of the application's components. 374 Similarly, the icon and label set for a component — for example, an 375 <code><a href="{@docRoot}guide/topics/manifest/activity-element.html"><activity></a></code> 376 element — are the default settings for each of the component's 377 <code><a href="{@docRoot}guide/topics/manifest/intent-filter-element.html"><intent-filter></a></code> 378 elements. If an 379 <code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> 380 element sets a label, but an activity and its intent filter do not, 381 the application label is treated as the label for both the activity and 382 the intent filter. 383 </p> 384 385 <p> 386 The icon and label set for an intent filter are used to represent a component 387 whenever the component is presented to the user as fulfilling the function 388 advertised by the filter. For example, a filter with 389 "{@code android.intent.action.MAIN}" and 390 "{@code android.intent.category.LAUNCHER}" settings advertises an activity 391 as one that initiates an application — that is, as 392 one that should be displayed in the application launcher. The icon and label 393 set in the filter are therefore the ones displayed in the launcher. 394 </p> 395 396 397 <h3 id="perms">Permissions</h3> 398 399 <p> 400 A <i>permission</i> is a restriction limiting access to a part of the code 401 or to data on the device. The limitation is imposed to protect critical 402 data and code that could be misused to distort or damage the user experience. 403 </p> 404 405 <p> 406 Each permission is identified by a unique label. Often the label indicates 407 the action that's restricted. For example, here are some permissions defined 408 by Android: 409 </p> 410 411 <p style="margin-left: 2em">{@code android.permission.CALL_EMERGENCY_NUMBERS} 412 <br/>{@code android.permission.READ_OWNER_DATA} 413 <br/>{@code android.permission.SET_WALLPAPER} 414 <br/>{@code android.permission.DEVICE_POWER}</p> 415 416 <p> 417 A feature can be protected by at most one permission. 418 </p> 419 420 <p> 421 If an application needs access to a feature protected by a permission, 422 it must declare that it requires that permission with a 423 <code><a href="{@docRoot}guide/topics/manifest/uses-permission-element.html"><uses-permission></a></code> 424 element in the manifest. Then, when the application is installed on 425 the device, the installer determines whether or not to grant the requested 426 permission by checking the authorities that signed the application's 427 certificates and, in some cases, asking the user. 428 If the permission is granted, the application is able to use the protected 429 features. If not, its attempts to access those features will simply fail 430 without any notification to the user. 431 </p> 432 433 <p> 434 An application can also protect its own components (activities, services, 435 broadcast receivers, and content providers) with permissions. It can employ 436 any of the permissions defined by Android (listed in 437 {@link android.Manifest.permission android.Manifest.permission}) or declared 438 by other applications. Or it can define its own. A new permission is declared 439 with the 440 <code><a href="{@docRoot}guide/topics/manifest/permission-element.html"><permission></a></code> 441 element. For example, an activity could be protected as follows: 442 </p> 443 444 <pre> 445 <manifest . . . > 446 <permission android:name="com.example.project.DEBIT_ACCT" . . . /> 447 <uses-permission android:name="com.example.project.DEBIT_ACCT" /> 448 . . . 449 <application . . .> 450 <activity android:name="com.example.project.FreneticActivity" 451 android:permission="com.example.project.DEBIT_ACCT" 452 . . . > 453 . . . 454 </activity> 455 </application> 456 </manifest> 457 </pre> 458 459 <p> 460 Note that, in this example, the {@code DEBIT_ACCT} permission is not only 461 declared with the 462 <code><a href="{@docRoot}guide/topics/manifest/permission-element.html"><permission></a></code> 463 element, its use is also requested with the 464 <code><a href="{@docRoot}guide/topics/manifest/uses-permission-element.html"><uses-permission></a></code> 465 element. Its use must be requested in order for other components of the 466 application to launch the protected activity, even though the protection 467 is imposed by the application itself. 468 </p> 469 470 <p> 471 If, in the same example, the {@code permission} attribute was set to a 472 permission declared elsewhere 473 (such as {@code android.permission.CALL_EMERGENCY_NUMBERS}, it would not 474 have been necessary to declare it again with a 475 <code><a href="{@docRoot}guide/topics/manifest/permission-element.html"><permission></a></code> 476 element. However, it would still have been necessary to request its use with 477 <code><a href="{@docRoot}guide/topics/manifest/uses-permission-element.html"><uses-permission></a></code>. 478 </p> 479 480 <p> 481 The 482 <code><a href="{@docRoot}guide/topics/manifest/permission-tree-element.html"><permission-tree></a></code> 483 element declares a namespace for a group of permissions that will be defined in 484 code. And 485 <code><a href="{@docRoot}guide/topics/manifest/permission-group-element.html"><permission-group></a></code> 486 defines a label for a set of permissions (both those declared in the manifest with 487 <code><a href="{@docRoot}guide/topics/manifest/permission-element.html"><permission></a></code> 488 elements and those declared elsewhere). It affects only how the permissions are 489 grouped when presented to the user. The 490 <code><a href="{@docRoot}guide/topics/manifest/permission-group-element.html"><permission-group></a></code> 491 element does not specify which permissions belong to the group; 492 it just gives the group a name. A permission is placed in the group 493 by assigning the group name to the 494 <code><a href="{@docRoot}guide/topics/manifest/permission-element.html"><permission></a></code> 495 element's 496 <code><a href="{@docRoot}guide/topics/manifest/permission-element.html#pgroup">permissionGroup</a></code> 497 attribute. 498 </p> 499 500 501 <h3 id="libs">Libraries</h3> 502 503 <p> 504 Every application is linked against the default Android library, which 505 includes the basic packages for building applications (with common classes 506 such as Activity, Service, Intent, View, Button, Application, ContentProvider, 507 and so on). 508 </p> 509 510 <p> 511 However, some packages reside in their own libraries. If your application 512 uses code from any of these packages, it must explicitly asked to be linked 513 against them. The manifest must contain a separate 514 <code><a href="{@docRoot}guide/topics/manifest/uses-library-element.html"><uses-library></a></code> 515 element to name each of the libraries. (The library name can be found in the 516 documentation for the package.) 517 </p> 518
