• res/drawable/ for images (PNG, JPEG, etc.)
• res/layout/ for XML-based UI layout specifications
• res/menu/ for XML-based menu specifications
• res/raw/ for general-purpose files (e.g., a CSV file of account information)
• res/values/ for strings, dimensions, and the like
• res/xml/ for other general-purpose XML files you wish to ship
We will cover all of these and more in later chapters of this book, particularly Chapter 19.
What You Get Out of It
When you compile your project (via ant or the IDE), the results go into the bin/ directory under your project root, specifically:
• bin/classes/ holds the compiled Java classes
• bin/classes.dex holds the executable created from those compiled Java classes
• bin/yourapp.ap_ holds your application’s resources, packaged as a ZIP file (where yourapp is the name of your application)
• bin/yourapp-debug.apk or bin/yourapp-unsigned.apk is the actual Android application (where yourapp is the name of your application)
The .apk file is a ZIP archive containing the .dex file, the compiled edition of your resources (resources.arsc), any un-compiled resources (such as what you put in res/raw/) and the AndroidManifest.xml file. It is also digitally signed, with the -debug portion of the filename indicating it has been signed using a debug key that works with the emulator, or -unsigned indicating that you built your application for release (ant release), but the APK still needs to be signed using jarsigner and an official key.
CHAPTER 3
Inside the Manifest
The foundation for any Android application is the manifest file: AndroidManifest.xml in the root of your project. Here is where you declare what is inside your application — the activities, the services, and so on. You also indicate how these pieces attach themselves to the overall Android system; for example, you indicate which activity (or activities) should appear on the device’s main menu (aka the launcher).
When you create your application, you will get a starter manifest generated for you. For a simple application, offering a single activity and nothing else, the auto-generated manifest will probably work out fine, or perhaps require a few minor modifications. On the other end of the spectrum, the manifest file for the Android API demo suite is over 1,000 lines long. Your production Android applications will probably fall somewhere in the middle.
Most of the interesting bits of the manifest will be described in greater detail in the chapters on their associated Android features. For example, the service element is described in greater detail in Chapter 30. For now, you just need to understand what the role of the manifest is and its general construction.
In the Beginning There Was the Root, and It Was Good
The root of all manifest files is, not surprisingly, a manifest element:
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
package="com.commonsware.android.search">
...
</manifest>
Note the namespace declaration. Curiously, the generated manifests apply it only on the attributes, not the elements (e.g., it’s manifest, not android:manifest). However, that pattern works, so unless Android changes, stick with their pattern.
The biggest piece of information you need to supply on the manifest element is the package attribute (also curiously not namespaced). Here you can provide the name of the Java package that will be considered the “base” of your application. Then, everywhere else in the manifest file that needs a class name, you can just substitute a leading dot as shorthand for the package. For example, if you needed to refer to com.commonsware.android.search.Snicklefritz in our example manifest, you could just use .Snicklefritz since com.commonsware.android.search is defined as the application’s package.
Permissions, Instrumentations, and Applications (Oh, My!)
Underneath the manifest element, you will find the following:
• uses-permission elements to indicate what permissions your application will need in order to function properly. See Chapter 29 for more details.
• permission elements to declare permissions that activities or services might require other applications hold in order to use your application’s data or logic. Again, more details are forthcoming in Chapter 29.
• instrumentation elements to indicate code that should be invoked on key system events, such as starting up activities, for the purposes of logging or monitoring.
• uses-library elements to hook in optional Android components, such as mapping services
• Possibly a uses-sdk element to indicate what version of the Android SDK the application was built for.
• An application element defining the guts of the application that the manifest describes.
In the following example the manifest has uses-permission elements to indicate some device capabilities the application will need — in this case, permissions to allow the application to determine its current location. And there is the application element, whose contents will describe the activities, services, and whatnot that make up the bulk of the application itself.
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
package="com.commonsware.android">
<uses-permission
android:name="android.permission.ACCESS_LOCATION" />
<uses-permission
android:name="android.permission.ACCESS_GPS" />
<uses-permission
android:name="android.permission.ACCESS_ASSISTED_GPS" />
<uses-permission
android:name="android.permission.ACCESS_CELL_ID" />
<application>
...
</application>
</manifest>
Your Application Does Something, Right?
The real meat of the manifest file is the children of the application element.
By default, when you create a new Android project, you get a single activity element:
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
package="com.commonsware.android.skeleton">
<application>
<activity android:name=".Now" android:label="Now">
<intent-filter>
<action android:name="android.intent.action.MAIN" />
<category android:name="android.intent.category.LAUNCHER" />
</intent-filter>
</activity>
</application>