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