Add page about building for devices. Also some tweaks.
Update version list with 2.3.3
Add info about Honeycomb GPL modules
Fine-tune description of builds vs devices
Change-Id: I2f7bfcb30a824ab6bc37152d2989f1f413703745
diff --git a/src/source/build-numbers.md b/src/source/build-numbers.md
index 0592939..6598ab8 100644
--- a/src/source/build-numbers.md
+++ b/src/source/build-numbers.md
@@ -20,20 +20,23 @@
releases, which use code names ordered alphabetically after tasty
treats.
+## Platform code names, versions, API levels, and NDK releases ##
+
The code names match the following version numbers, along with
API levels and NDK releases provided for convenience:
-Code name | Version | API level
----------------|---------|------------
-(no code name) | 1.0 | API level 1
-(no code name) | 1.1 | API level 2
-Cupcake | 1.5 | API level 3, NDK 1
-Donut | 1.6 | API level 4, NDK 2
-Eclair | 2.0 | API level 5
-Eclair | 2.0.1 | API level 6
-Eclair | 2.1 | API level 7, NDK 3
-Froyo | 2.2.x | API level 8, NDK 4
-Gingerbread | 2.3.x | API level 9, NDK 5
+Code name | Version | API level
+---------------|--------------|------------
+(no code name) | 1.0 | API level 1
+(no code name) | 1.1 | API level 2
+Cupcake | 1.5 | API level 3, NDK 1
+Donut | 1.6 | API level 4, NDK 2
+Eclair | 2.0 | API level 5
+Eclair | 2.0.1 | API level 6
+Eclair | 2.1 | API level 7, NDK 3
+Froyo | 2.2.x | API level 8, NDK 4
+Gingerbread | 2.3 - 2.3.2 | API level 9, NDK 5
+Gingerbread | 2.3.3 | API level 10
Starting with Cupcake, individual builds are identified with a short
build code, e.g. FRF85B. The first letter is the code name of the
@@ -50,12 +53,14 @@
common that minor variations added to an existing build re-use the
same date code as that existing build.
+## Source code tags and builds ##
+
Starting with Donut, the exact list of tags and builds is in the
following table:
Build | Tag | Notes
-------|--------------------|-----------------------------------
-DRC83 | android-1.6_r1.1 earliest Donut version, ADP1, ADP2
+DRC83 | android-1.6_r1.1 | earliest Donut version, ADP1, ADP2
DRC92 | android-1.6_r1.2
DRD08 | android-1.6_r1.3
DRD20 | android-1.6_r1.4
@@ -76,7 +81,8 @@
FRG83G | android-2.2.2_r1 | latest Froyo version, Nexus One
GRH55 | android-2.3_r1 | earliest Gingerbread version, Nexus S
GRH78 | android-2.3.1_r1 | Nexus S
-GRH78C | android-2.3.2_r1 | latest Gingerbread version, Nexus S
+GRH78C | android-2.3.2_r1 | Nexus S
+GRI40 | android-2.3.3_r1 | latest Gingerbread version, Nexus S, Nexus One
The branches donut, eclair, froyo, gingerbread represent development
branches that do not exactly match configurations that were tested
@@ -84,3 +90,15 @@
the official tagged releases, and those haven't been as thoroughly
tested.
+## Honeycomb GPL modules ##
+
+For Honeycomb, the entire platform source code isn't available.
+However, the parts of Honeycomb licensed under the GPL and LGPL
+are available under the following tags:
+
+Build | Tag | Notes
+-------|--------------------|-----------------------------------
+HRI39 | android-3.0_r1 | earliest Honeycomb version, Xoom
+HRI66 | android-3.0_r1.1 | Xoom
+HWI69 | android-3.0_r1.2 | Xoom
+HRI93 | android-3.0_r1.3 |
diff --git a/src/source/building-devices.md b/src/source/building-devices.md
new file mode 100644
index 0000000..0c88a28
--- /dev/null
+++ b/src/source/building-devices.md
@@ -0,0 +1,149 @@
+<!--
+ Copyright 2010 The Android Open Source Project
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+
+# Building for devices #
+
+This page complements the main page about [Building](building.html) with information
+that is specific to individual devices.
+
+The only supported device is Nexus S, a.k.a. "crespo". Nexus S is the recommended
+device to use with the Android Open-Source Project. Nexus One a.k.a. "passion" is
+experimentatal and unsupported. Android Developer Phones (ADP1 and ADP2, a.k.a. "dream"
+and "sapphire") are obsolete, were experimental and unsupported in froyo, and can't
+be used with gingerbread.
+
+## Building fastboot and adb ##
+
+If you don't already have those tools, fastboot and adb can be built with
+the regular build system. Follow the instructions on the page about
+[building](building.html), and replace the main `make` command with
+
+ $ make fastboot adb
+
+## Booting into fastboot mode ##
+
+During a cold boot, the following key combinations can be used to boot into fastboot mode,
+which is a mode in the bootloader that can be used to flash the devices:
+
+Device | Keys
+---------|------
+crespo | Press and hold *Volume Up*, then press and hold *Power*
+passion | Press and hold the trackball, then press *Power*
+sapphire | Press and hold *Back*, then press *Power*
+dream | Press and hold *Back*, then press *Power*
+
+Also, on devices running froyo or later where adb is enabled,
+the command `adb reboot bootloader` can be used to reboot from
+Android directly into the bootloader with no key combinations.
+
+## Unlocking the bootloader ##
+
+It's only possible to flash a custom system if the bootloader allows it.
+
+This is the default setup on ADP1 and ADP2.
+
+On Nexus One and Nexus S, the bootloader is locked by default. With the
+device in fastboot mode, the bootloader is unlocked with
+
+ $ fastboot oem unlock
+
+The procedure must be confirmed on-screen, and deletes the user data for
+privacy reasons. It only needs to be run once.
+
+On Nexus One, the operation voids the warranty and is irreversible.
+
+On Nexus S, the bootloader can be locked back with
+
+ $ fastboot oem lock
+
+## Obtaining proprietary drivers ##
+
+While it's possible to build and run a system using exclusively source code
+from Android Open-Source Project, such a system can only use the devices'
+hardware capabilities for which Open-Source drivers exist.
+
+Official drivers for Nexus S can be downloaded from
+[Google's Nexus driver page](http://code.google.com/android/nexus/), which
+add access to additional hardware capabilities with non-Open-Source drivers.
+
+There are no official drivers for Nexus One, ADP2 or ADP1.
+
+Each driver comes as a self-extracting script in a compressed archive.
+After uncompressing each archive, run the included self-extracting script
+from the root of the source tree, confirm that you agree to the terms of the
+enclosed license agreement, and the drivers and their matching makefiles
+will get installed in the `vendor/` hierarchy of the source tree.
+
+In order to make sure that the newly installed drivers are properly
+taken into account after being extracted, the existing output of any previous
+build needs to be deleted with
+
+ $ make clobber
+
+## Picking and building the configuration that matches a device ##
+
+The steps to configure and build the Android Open-Source Project
+are described in the page about [Building](building.html).
+
+The recommended builds for the various devices are available through
+the lunch menu, accesed when running the `lunch` command with no arguments:
+
+Device | Build configuration
+---------|---------------------
+crespo | full_crespo-userdebug
+passion | full_passion-userdebug
+sapphire | full_sapphire-userdebug
+dream | full_dream-userdebug
+
+## Flashing a device ##
+
+Set the device in fastboot mode if necessary (see above).
+
+Because user data is typically incompatible between builds of Android,
+it's typically better to delete it when flashing a new system.
+
+ $ fastboot erase cache
+ $ fastboot erase userdata
+
+An entire Android system can be flashed in a single command: this writes
+teh boot, recovery and system partitions together after verifying that the
+system bring flashed is compatible with the installed bootloader and radio,
+and reboots the system.
+
+ $ fastboot flashall
+
+On crespo, sapphire and dream (but not on passion), the commands above can
+be replaced with a single command
+
+ $ fastboot -w flashall
+
+### Nexus S Bootloader and Cell Radio compatibility ###
+
+On Nexus S, each version of Android has only been thoroughly tested with
+on specific version of the underlying bootloader and cell radio software.
+However, no compatibility issues are expected when running newer systems
+with older bootloaders and radio images according to the following table:
+
+Android Version | Preferred Bootloader | Preferred Radio | Also possible
+----------------|----------------------|-----------------|--------------
+2.3 to 2.3.2 | I9020XXJK1 | I9020XXJK8
+2.3.3 | I9020XXKA3 | I9020XXKB1 | versions from 2.3
+
+If you're building a new version of Android, if your Nexus S has an older
+bootloader and radio image that is marked as being also possible in the
+table above but is not recognized by the build system, you can locally
+delete the version-bootloader and version-baseband lines in
+device/samsung/crespo/board-info.txt
diff --git a/src/source/building.md b/src/source/building.md
index e026f5a..5ddcd11 100644
--- a/src/source/building.md
+++ b/src/source/building.md
@@ -41,22 +41,25 @@
If run with no arguments `lunch` will prompt you to choose a target from the menu.
-All build targets take the form DEVICE-BUILDTYPE, where the DEVICE is a codename
-referring to the particular hardware:
+All build targets take the form BUILD-BUILDTYPE, where the BUILD is a codename
+referring to the particular feature combination:
-Codename | Device
------------|-----------
-passion | Nexus One
-crespo | Nexus S
-generic | emulator
+Build name | Device | Notes
+
+generic | emulator | lowest-common denominator
+full | emulator | fully configured with all languages, apps, input methods
+full_crespo | crespo | `full` build running on Nexus S ("crespo")
and the BUILDTYPE is one of the following:
Buildtype | Use
------------|--------------------------------------
user | limited access; suited for production
-userdebug | like "user" but with `su` access; preferred for debugging
-eng | unrestricted access
+userdebug | like "user" but with root access and debuggability; preferred for debugging
+eng | development configuration with additional debugging tools
+
+For more information about building for and running on actual hardware, see
+[Building for devices](building-devices.html)
## Build the Code ##
@@ -86,6 +89,9 @@
The `-w` option wipes the `/data` partition on the device; this is useful for your first time flashing a particular device, but is otherwise unnecessary.
+For more information about building for and running on actual hardware, see
+[Building for devices](building-devices.html)
+
### Emulate an Android Device ###
The emulator is added to your path automatically by the build process. To run the emulator, type
diff --git a/src/source/sidebar.md b/src/source/sidebar.md
index e34e247..4a9f797 100644
--- a/src/source/sidebar.md
+++ b/src/source/sidebar.md
@@ -3,6 +3,7 @@
- [Initializing the Build Environment](initializing.html)
- [Downloading the Source](downloading.html)
- [Building and Running](building.html)
+- [Building for Devices](building-devices.html)
# Navigating the Source #