Android OS Forum banner

1 - 2 of 2 Posts

·
Wannabe Developer
Joined
·
404 Posts
This was created by the "Human Brain":

Before I start, it needs to be said
: What you will find here is mostly a compilation of dozens of hints, guides and wiki posts available on the web, with a touch of my knowledge. The goal was to create a guide that has all the links, all the tools and the advanced steps, required to make your own Android ROM, covered. This guide was written for and tested on a HTC Hero. Other devices may follow the same route, but check first. This guid uses Linux commands and tools and assumes you have access to a PC running Linux, and basic Linux knowledge.

If at any stage you don't understand what this text is about, stop and go away. I don't take any responsibility for devices damaged or otherwise broken because of following this guide. While slim, there is always a chance your device will become a useless brick after this. You have been warned.

Since some people don't know it, let's start with explaining what a ROM (or rather a ROM image) actually is. In case of Android devices a ROM image is a binary representation of an entire "disk" with its partition table, file systems and all the files. I put "disk" in quotes, since there are no disk drives in smartphones. Those were replaced by flash memory chips.
Official (HTC Hero) ROM updates are released as RUUs (RUU = ROM Update Utility), which you run on your (Windows) PC to get the device updated automatically. However convenient, RUUs have a major fault in the context of ROM customization: they don't support any. Fortunately some of the big brains in the Android community release RUUs re-packaged into signed update files, which in turn allow for whatever ROM customization you can imagine.

The "signed update" type ROM image always contains the following components:
  1. boot.img - This file is a binary representation of the root file system of the device. It contains the system kernel and all files required to start the core part of Android
  2. system - This is a directory containing all files found under /system on a running Android device. It has exactly the same layout.
  3. META-INF - This is directory containing the update manifest and script. The manifest is a file which lists all file included in the update, with their SHA1 checksums. The update script is used to apply the update on a device
This guide is using a "signed update".

These are the prerequisites for this guide:
  1. HTC Hero - Surprised? ;) Your device must be rooted already and either be able to use "fastboot usb" or have a custom recover image flashed. If your device is not rooted, you're stuck with using RUUs.
  2. Linux- Either on a physical machine or in a VM that supports USB. Any recent distribution will do. I'm using Ubuntu 9.10.
  3. Android SDK - Version 1.5 or 1.6. You must have this installed and configured before proceeding. These are the tools you will need to build:
    • adb
    • fastboot
    • mkbootfs
    • mkbootimg
  4. Sun Java JRE - If you have configured the Android SDK yourself, you most likely have Java 5 (JDK 5) already. If not, get it, otherwise get the tools as binaries (below), and Java 6 JRE.
  5. split_bootimg.pl - This is a Perl script which splits the boot.img file into a kernel and ramdisk part. Download it from android-dls.com.
  6. zip, gzip, cpio, patch - Those are utilities we will need to work with the update image. Any reasonable Linux distribution has them by default. If not, get one that does.
Download, build and install all prerequisites before continuing as this step will not be covered in this quide. If you don't know how to do this, stick to official ROMs. Alternatively you can download all the binaries (except Java!) from this server.

On Linux, you can also run the following commands to automate the initial environment setup:

mkdir -p ~/android/romcd ~/android/romwget -q http://www.szmit.eu/files/prep -O ./prep[ -f ./prep ] && bash ./prep path_to_update_zip
Where path_to_update_zip is the full path to the source ROM packaged as an "update.zip", e.g.:~/download/modaco_update.zip. By using this method you will save yourself some work and will be able to skip straight to Step 4.

Step 0 - Working directory layout


Once you have all the prerequisites in place, create a working directory under /usr/src/android and inside it create two more directories updates and tools. Set your WKD environment variable to/usr/src/android/updates - this will be where all the work is done. Next, add /usr/src/android/tools to your PATH and place all the tool binaries mentioned in prerequisites here (just the binaries!). The whole process should look like this:

mkdir -p /usr/src/android/{updates,tools}export WKD=/usr/src/android/updatesexport PATH=$PATH:/usr/src/android/toolsStep 1 - Getting a "signed update" type ROM

Paul from MoDaCo, better know for his custom "MoDaCo Custom ROM" for the Hero, is also publishing new HTC ROMs (including leaked ones!) as they become available. The up-to-date list, with links, is on android.modaco.com. This guide is using the "HTC Generic 2.73.405.38" ROM. Download the file into WKD like this:

wget url_to_ROM_file -O $WKD/update-source.zipOnce downloaded, unzip the file:

cd $WKDmkdir src cd !$unzip ../update-source.zipStep 2 - Splitting the boot image

If you don't want to modify the boot image, go to step 6. Otherwise read on. Before the boot image can be modified we need to unpack it from the boot.img file into something we can work with. This is done using the slipt_bootimg.pl script, like so:

mkdir -p $WKD/dst/bootcd !$split_bootimg.pl $WKD/src/boot.imgYou should now have two files in $WKD/dst/boot - boot.img-kernel and boot.img-ramdisk.gz. In this guide we're only interested in the later one, which is the ramdisk image that holds all core system files, except the kernel.
Step 3 - Preparing the ramdisk for modification

The ramdisk file is in a compressed cpio archive format, which cannot be worked on directly. To get in workable form do the following:

cd $WKD/dst/boot && mkdir ramdiskcd !$gzip -dc $WKD/dst/boot/boot.img-ramdisk.gz | cpio -iThis will unpack the ramdisk image into $WKD/dst/boot/ramdisk/ and the fun part can begin.

Step 4 - Modifying the boot image ramdisk

Frankly, your possibilities here aren't huge, but if you want an image that stores applications on your SD card, and can arbitrary commands at boot this is where changes need to be applied. We will root the system in step 6.

Android uses several init scripts, but we're only interested in init.rc. We will modify this file to redirect user app storage from phone memory to SD card. Before you can use this image though, your SD card MUST have two partitions - the first one is a FAT32 partition, and the second one MUST be an ext3 partition smaller than 512MB. It's more than enough to store hundreds of apps.
To make things easier, I have created a patch file that you simply need to apply to the original init.rc script. This will add entries required to mount the ext3 partition and redirect /data/app and /data/app-private to it. You can download the patch from this server. Once dowloaded, put the file into WKD.

To apply this patch, run:

cd $WKD/dst/boot/ramdisk && patch -p0 < $WKD/init.rc.patchThat's it! We're ready to repack the file into a boot image.

Step 5 - Creating the new boot image

To create your new boot.img file run the following:

cd $WKD/dst/bootmkbootfs ./ramdisk | gzip > boot.img-ramdisk.gzmkbootimg --kernel ./boot.img-kernel \--ramdisk ./boot.img-ramdisk.gz \--cmdline "no_console_suspend=1 console=null" \-o ./boot.img --base 0x19200000Now move the new boot.img file to $WKD/dst/boot.img and remove the boot directory. It is no longer needed.

cd $WKD/dst/ && mv boot/boot.img ./ && rm -rf ./boot

Step 6 - Rooting the ROM and other fun


Before we can have some fun with the rest of the ROM, we need to copy the source files to our destination directory. If you have followed step 2 to 5, run the following:

cp -pR $WKD/src/{META-INF,system} $WKD/dst/otherwise run:

cp -pR $WKD/src/* $WKD/dst/Now we have a working copy of all the files from the update, and can apply some changes to them. First, we will add the possibility of elevating privileges to become root. By default, this is not possible on Android devices like the HTC Hero. This is how you can enable this functionality. Download "Superuser" from XDA Developers. "Superuser" is an app that controls which apps can use/system/bin/su to escalate privileges to root.
Save and unzip the file in $WKD. Then run the following:

cp $WKD/Superuser.apk $WKD/dst/system/app/cp $WKD/su $WKD/dst/system/bin/

You also need to modify the ROM update script to change the default permissions for /system/bin/suso it can be used to elevate privileges to root. The script is in $WKD/dst/META-INF/com/google/android/update-script. Open it in your favorite editor and find the line starting withset_perm 0 2000 0550 SYSTEM:etc/init.goldfish.sh and after it add the following set_perm 0 0 04755 SYSTEM:bin/su. That's it. The ROM is now rooted.

Next, since I'm in Europe I modify change the GPS configuration so the service uses European time servers as opposed to North American, simply because they're closer, there's more of them and there's generally less latency and jitter involved. To do this edit the gps.conf file:

sed -e 's|north-america.pool.ntp.org|europe.pool.ntp.org|g' \< $WKD/dst/system/etc/gps.conf \> /tmp/gps.confmv /tmp/gps.conf $WKD/dst/system/etc/gps.conf

If you want to prevent your data partition being wiped clean during the update, remove the all lines BELOW this one write_raw_image PACKAGE:boot.img BOOT:. If you don't do this, the update will perform what essentially translates into a factory master reset. Keep that in mind. However if you do not wipe the data partition, you must manually delete all files in /data/dalvik-cache on the device. This is best done from recovery mode. I will leave this to you as an exercise.

This is usually as far as I go with the changes, since from now on I will be able to do whatever else is needed on the device itself. But if you want to make more changes, go ahead - but make sure you know what you're doing here. You could, for example, disable or change the boot sound and graphics. Google should have the answers for you.

Step 7 - Packaging and signing the modified update file

This step is quite straightforward and involves "zipping" the update directory and cryptographically signing the resulting archive. Do do this, run the following:

cd $WKD/dst/zip -r update-dst.zip *java -classpath $WKD/../tools/testsign.jar testsign \ update-dst.zip update-signed.zip

You should now have a file named update-signed.zip in $WKD/dst/. Next, you need to upload the file to your device.

Step 8 - Uploading the modified update file

Connect your device to the PC via USB. Make sure you have USB debugging enabled in device settings. DO NOT mount the SD card on your PC. Next upload the file:

adb push $WKD/dst/update-signed.zip /sdcard/update.zip

The next step differs for devices that have a custom recovery image already flashed, and those that don't. Let's start with the later. Keep in mind that this is based on Amon-Ra Recovery Image for Hero, version 1.3.2.

Step 9 - Backing up current ROM

If you don't have the custom recovery image flashed already, you must boot your device using fastboot. This requires a pre-rooted device or a ROM that doesn't disable the "fastboot usb" option. HTC have removed that option with their 2.73.x series of ROMs, but there's ways around it (flashrec or Golden Card)- Google it.

Connect your device to the PC via USB. Make sure you have USB debugging enabled in device settings. DO NOT mount the SD card on your PC. Run the following command:

adb shell reboot bootloader

This will bring you to the device bootloader, and you should see FASTBOOT USB in the third last line. If you don't, your bootloader is probably patched. If you do see it however, run the following:

fastboot boot recovery_imagewhere recovery_image is the path to the recovery image file.
Once the device starts, you should see a screen similar to this one:

Select the "Backup/Restore" option and from the next screen select "Nandroid backup". Confirm with the "Home" key when requested.

This will create a full backup of your current ROM, so in case something goes wrong you can recover. Do not reboot your device after the backup was made. We still need the recovery tools.

Step 10 - Flashing the custom ROM

Before you proceed: By default this procedure will wipe your data partition clean, which translates to a factory master reset. That is unless you have removed the required lines from the ROM update script as described later, and wiped the Dalvik cache directory.

OK, nine steps later the time has come to test your new, custom made ROM for real. From the recovery menu select "Flash update image", followed by "Apply sdcard:update.zip". Confirm with the "Home" key when requested. This will flash your custom ROM onto the device.

Once this process finishes, your device is ready to boot into its shiny new ROM. Go back to the main "Android system recovery" screen and select "Reboot system now" hoping for the best. If all went fine, your device will boot with the new ROM. It may take a fair few minutes, so be patient. If it takes longer than 10 minutes, you're in trouble and the best option is to boot into recovery mode and restore the previously backed-up ROM.

That's it. Enjoy your new found power!

Now, I want to give credit where credit is due, so here's a list of sites I have used to compile this guide:
Thanks to everyone who shared their knowledge, time and skills in providing all the various bits of information.
 

·
Registered
Joined
·
4 Posts
this is excellent - i spent the last 24 hours looking for a well written guide on exactly this topic. i am glad i decided to click through all the pages of posts!
 
1 - 2 of 2 Posts
Top