Android Platform Customization
Status: DRAFT
Last Updated: February 2009
Android Platform Customization ............................................................................... 1
Introduction................................................................................................................ 1
Configuring a New Build Target................................................................................. 1
Hardware Configuration............................................................................................. 1
Boot Screen Customization ....................................................................................... 2
Network Customization Platform Support.................................................................. 2
Network Configuration ........................................................................................... 2
Build-time APN Configuration ................................................................................ 2
APN Configuration at run time ............................................................................... 3
Customizing the Pre-loaded Applications .................................................................. 3
Browser Bookmark Customization ............................................................................ 4
Email Provider Customization ................................................................................... 5
Platform Themeability ................................................................................................ 8
Themes and Styles ................................................................................................ 8
Animations ............................................................................................................. 8
Customizing Android Resources Per Product ........................................................... 9
System Properties ................................................................................................... 10
Introduction
Android is designed to allow platform developers to extend and customize the default distribution in
order to differentiate product offerings and add proprietary value-add. This document outlines the
recommended best practices for organizing platform customizations and managing product
configurations to minimize fragmentation and overhead associated with code line management.
Configuring a New Build Target
(TODO: Take most of this from http://go/android-pdk/build_new_device.html)
All proprietary platform customizations should be placed under the vendor/
/ directory.
The recommended layout is:
/vendor//products
/vendor//apps
/vendor//providers
/vendor//services
/vendor//libs
Hardware Configuration
TODO: We need to add instructions / documentation on how display values, keyboard state, nav
controller, etc. are reported through android.content.Configuration.
Boot Screen Customization
At startup, Android displays a splashscreen image while booting the device. This splash screen is
configurable, as follows:
1. Create a 320x480 image (say screen.jpg)
2. Use the ImageMagick tool convert:
convert screen.jpg screen.r
3. Use the rgb2565 tool to convert the image to 565 format:
rgb2565 < screen.rgb > screen.565
4. Use fastboot to flash the image to the device:
fastboot flash splash1 screen.565
Network Customization Platform Support
Access Point Name (APN) Configuration
The platform will store network configurations as a resource which will be compiled into binary
form at build time. The XML representation of this resource in the source tree is located at:
//android/frameworks/base/core/res/res/xml/apns.xml. Each network
configuration is stored in an XML element following this syntax:
Note that the default APNs file listed above is an empty file with no configured APNs. Platform
developers should not modify this file, but should instead configure APNs by product at build
time (see Build-time APN Configuration below).
Build-time APN Configuration
To set the APN configuration for a particular product target, platform developers should add an
apns-conf.xml file to the product configuration, rather than modifying the default platform
APNs. This allows multiple products, all with different APNs, to be built off the same code
base. To configure APNs at the product level:
Add the following line to the product configuration file (eg: vendor/acme/products/myphone-
us.mk):
PRODUCT_COPY_FILES := vendor/acme/etc/apns-conf-us.xml:system/etc/
apns-conf.xml
APN Configuration at run time
At runtime, the Android platform will read the APNs from the following file:
system/etc/apns-conf.xml
The platform will support the following run-time network configuration methods to choose the
appropriate APN from the list of configured APNs:
• Automatic Configuration: At boot time, Android will determine the correct network
configuration based on the MCC and MNC from the SIM card and automatically configure all
network settings.
• Manual Configuration: The platform will also support runtime (user) manual selection of
network settings by name "T-Mobile US", and will support manual network configuration entry.
• WAP / SMS Push Configuration: The network configurations are standard Android resources
which can be upgraded at runtime by installing a new system resource APK package. It will be
possible to develop a network configuration service which listens to a specific binary SMS port
for binary SMS messages containing the network configurations. NOTE: The implementation
will likely be network operator dependent due to inconsistent SMS ports, binary SMS formats,
etc.
Customizing the Pre-loaded Applications
To customize the list of Android packages (applications, input methods, providers, services, etc.) for a
particular product, set the PRODUCT_PACKAGES property in the product configuration. For
example:
PRODUCT_PACKAGES := \
AcmeMail \
AcmeIM \
AcmHomeScreen \
AcmeMaps \
AcmeSystemUpdater
The package names should correspond to the LOCAL_PACKAGE_NAME specified for each package's
build target. For example, the Android.mk build target for AcmeMail, referenced above, may look
like:
# Build the AcmeMail application
LOCAL_PATH:= $(call my-dir)
include $(CLEAR_VARS)
LOCAL_MODULE_TAGS := user development
LOCAL_SRC_FILES := $(call all-java-files-under,src,tests)
LOCAL_STATIC_JAVA_LIBRARIES := acmelogin-client
# Specify the package name
LOCAL_PACKAGE_NAME := AcmeMail
# Specify the certificate used to sign the application
LOCAL_CERTIFICATE := vendor/acme/certs/app
include $(BUILD_PACKAGE)
# Build the login client static library
include $(LOCAL_PATH)/client/Android.mk
Note that the home screen is just an Android application that can be customized through changing
source code and application resources (Java source, layouts, etc.) or replaced entirely.
Browser Bookmark Customization
The browser bookmarks are stored as string resources in the Browser application: //android/
packages/apps/Browser/res/values/strings.xml. The bookmarks are defined as a simple value string
array called "bookmarks". Each bookmark entry is stored as two array values -- the first is the
bookmark name and the second is the bookmark URL. For example:
- Google
- http://www.google.com/
- Yahoo!
- http://www.yahoo.com/
- MSN
- http://www.msn.com/
- MySpace
- http://www.myspace.com/
- Facebook
- http://www.facebook.com/
- Wikipedia
- http://www.wikipedia.org/
- eBay
- http://www.ebay.com/
- CNN
- http://www.cnn.com/
- New York Times
- http://www.nytimes.com/
- ESPN
- http://espn.go.com/
- Amazon
- http://www.amazon.com/
- Weather Channel
- http://www.weather.com/
- BBC
- http://www.bbc.co.uk/
It is possible to configure a single build to use different bookmarks at runtime based on locale, MCC,
MNC tupple, or other identifiers. As with all Android application resources, the platform will load
alternate resources based on the platform configuration values. See Supporting Alternate Resources
for Alternate Languages and Configurations in the Android SDK for details. To configure bookmarks
for a specific mobile network operator, place the customized bookmarks in a separate strings.xml
file and place under a MNO-specific resource folder by Mobile Network Code (MNC). For example,
Browser/res/values-mccXXX-mncYYY/strings.xml where XXX and YYY are the 3-digit MCC
and 2-3 digit MNC values.
Note that Android loads any configuration-specific resources as override values for the default values,
so it is only necessary to include the bookmarks string-array values in this file.
To configure bookmarks at build time by product target, see Customizing Android Resources Per
Product.
Email Provider Customization
The default email provider settings are stored as string resources in the Email application: //android/
packages/apps/Email/res/xml/providers.xml. The email For example:
It is possible to configure a single build to use different email providers at runtime based on locale,
MCC, MNC tupple, or other identifiers. As with all Android application resources, the platform will
load alternate resources based on the platform configuration values. See Supporting Alternate
Resources for Alternate Languages and Configurations in the Android SDK for details. To configure
email providers for a specific mobile network operator, place the customized providers in a separate
providers.xml file and place under a MNO-specific resource folder by Mobile Network Code
(MNC). For example, Email/res/xml-mccXXX-mncYYY/providers.xml where XXX and YYY
are the 3-digit MCC and 2-3 digit MNC values.
To configure bookmarks at build time by product target, see Customizing Android Resources Per
Product.
Platform Themeability
Android applications may contain UI elements defined in XML resources such as layouts, animations,
images, etc. There current SDK documentation covers styles and themes for applications:
http://code.google.com/android/reference/available-resources.html.
Themes and Styles
System level styles are defined in //android/framework/base/core/res/res/values/
styles.xml
Animations
The platform supports configurable animations for window and view transitions defined in
XML. The system level animations are configured in global resource files in //android/
framework/base/core/res/res/anim/
To configure themes, styles and animations at build time by product target, see Customizing Android
Resources Per Product. This is strongly prefered to modifying the standard resources, as it will avoid
the need to do complicated merges for each platform update.
Notes:
• Configuring themes at runtime (user-selectable themes) is not currently supported in Android
Customizing Android Resources Per Product
The Android build system provides a mechanism to specify resource files that should be applied on
top of the defaults for a particular product. To activate it, a project buildfile (e.g. dream.mk) should be
modified to set PRODUCT_PACKAGE_OVERLAYS to a path relative to your top. That path becomes a
shadow root searched along with your top when aapt searches for resources.
For example if you have a myapp application living (from top):
packages/apps/myapp/res/values/strings.xml
you could set up "PRODUCT_PACKAGE_OVERLAYS := vendor/foobar/overlay" and add
vendor/foobar/overlay/packages/apps/myapp/res/values/strings.xml
Any strings or string arrays found in the overlay strings.xml file would replace those found in the
app itself.
Notes:
• Currently only resources (res dir) are supported. No Assets at this time and certainly no code
modification.
• If you just needed to make changes to that just one file you need just create that one. It's a
sparsely populated mirror of the core tree.
• If you need to modify locale-specific resources or any other flavor, that is supported.
• Any files in a values* (values, values-en-rGB, etc) is overlaid on a resource by resource
basis. You need just have the select strings you need to modify and the rest will be inherited
from the core defaults. Note that compound resources like string-array's are treated as a
single entity and replaced entirely.
• Files outside values (but still in res, drawables for example) are overlaid on a file basis.
• You can overlay a flavor that doesn't exist in core. For example you can define values-
mcc262-en/strings.xml in your overlay with no corresponding core values defined and the
strings will be used appropriately.
• Multiple overlays can be specified. First listed has precedence.
• If you really want to get dirty you can specify overlay dirs directly to aapt. Pass it multiple -S
args with the path from top for either the core res directory or the overlay res directory as
needed. Again it's left to right precedence. From the example above:
aapt package -z -u -c en_US ... -S vendor/foobar/overlay/
packages/apps/myapp/res -S packages/apps/myapp/res
Issues
• You shouldn't do anything that modifies the java code. Since resources are accessed by an
R value constant, adding or removing a resource will shuffle values around and potentially
break library use between compile types. You don't have a method to remove a resource,
but if you add a drawable for example it could be a problem. aapt will be enhanced to fail if
you add a resource.
• If the apps move between branches you need to fix up the overlay dir too. It needs the same
path from shadow-root to app as the top to app path.
• Doesn't currently complain if you redefine a resource twice in the same overlay file.
• Resources outside of the values are o
浙公网安备 33021202002483