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