Howto Build Android KitKat (4.4) for the Google Nexus 5

Howto Build Android KitKat (4.4) for the Google Nexus 5

December 1, 2013

NOTE: If you know what this is, and just want to start with a basically working source tree, skip to the section titled “Just Build the Thing ™.”

Overview

This page describes the steps necessary to compile the Android Open Source Project (AOSP) sources into a working phone image for the Google Nexus 5 (Here-forth called “hammerhead.”)

If the process of building Android sources is new to you, please start by reading the Android documentation on “Downloading and Building,” in full.

This method includes:

1. Android Open Source Project as a basis
2. Additional proprietary files for the hammerhead, to enable GPS, comms, etc.
3. Additional proprietary files to support the Google Apps suite (Play store, GMail, et al.)
4. In-tree kernel build from source

Obtain the AOSP Sources

The Android page on Building for Devices tells us to use the android-4.4_r1 tag for the Hammerhead. Incidentally, as per the Google release notification, this is the same baseline used for the KRT16M factory image.

This procedure is well documented:

1 2	repo init -u https: //android .googlesource.com /platform/manifest -b android-4.4_r1 repo sync

Obtain the Vendor Proprietary Files

There are a few methods to do this, but the (at face value) easiest is to download the vendor files from the Nexus Device Binaries page.

1 2 3

wget https: //dl .google.com /dl/android/aosp/broadcom-hammerhead-krt16m-bf9b8548 .tgz wget https: //dl .google.com /dl/android/aosp/lge-hammerhead-krt16m-0efa9c33 .tgz wget https: //dl .google.com /dl/android/aosp/qcom-hammerhead-krt16m-53cf1896 .tgz

Now, untar the packages, and run the extractor scripts:

1 2	for f in *.tgz; do tar xzf $f; done for extractor_script in *.sh; do bash $extractor_script; done

After you go through the EULAs and type “I ACCEPT”, once for each extractor, you’ll have directory trees at vendor/broadcom/hammerhead, vendor/lge/hammerhead, vendor/qcom/hammerhead.

Now, in the past, these proprietary binary releases have been fairly comprehensive. Unfortunately, the LG and Qualcomm drops appear to be missing some critial files. (Take my word for it — you won’t have 3G / cellular connectivity.)

If you look at proprietary-blobs.txt and vendor_owner_info.txt (both in the device/lge/hammerhead project), you’ll see that the following files are mentioned, but are not present at this point in the vendor trees.

Missing from vendor/lge/hammerhead:

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17

/system/app/OmaDmclient .apk /system/etc/DxHDCP .cfg /system/vendor/bin/vss_init /system/vendor/firmware/discretix/dxhdcp2 .b00 /system/vendor/firmware/discretix/dxhdcp2 .b01 /system/vendor/firmware/discretix/dxhdcp2 .b02 /system/vendor/firmware/discretix/dxhdcp2 .b03 /system/vendor/firmware/discretix/dxhdcp2 .mdt /system/vendor/lib/libDxHdcp .so /system/vendor/lib/libvdmengine .so /system/vendor/lib/libvdmfumo .so /system/vendor/lib/libvss_common_core .so /system/vendor/lib/libvss_common_idl .so /system/vendor/lib/libvss_common_iface .so /system/vendor/lib/libvss_nv_core .so /system/vendor/lib/libvss_nv_idl .so /system/vendor/lib/libvss_nv_iface .so

And these, from vendor/qcom/hammerhead:

1 2	/system/app/shutdownlistener .apk /system/app/TimeService .apk

Note: actually, OmaDmclient.apk is probably the only one that has to do with cellular networks. (See OMA DM description.)

So, to fix this, we need to do two things:

1. Obtain the binaries;
2. Add them to the build system.

For the first, it is possible to rip the binaries from the KRT16M factory image. To do this, you can either simply pull them from a working (stock) hammerhead device, as mentioned here — or, you can rip them from the Factory image file directly. The second method is clearly more repeatably correct, so let’s go that route.

Get the factory image release and untar it:

1 2 3

wget https: //dl .google.com /dl/android/aosp/hammerhead-krt16m-factory-bd9c39de .tgz tar xzf hammerhead-krt16m-factory-bd9c39de.tgz cd hammerhead-krt16m

Decompress that actual phone image:

1	unzip image-hammerhead-krt16m.zip

At this point, you will see the system partition, system.img. To convert it to something mountable, you need to run it through the simg2img tool that is built with AOSP by default. (When you build android, it shows up at $TOP/out/host/linux-x86/bin/simg2img):

1	simg2img system.img system.img.raw

Now, mount the thing:

1	mount -oloop -t ext4 system.img.raw /mnt

From here, you’ll have to copy the files listed above, from the /mnt, into your build tree. There’s undoubtedly countless ways to do that, but I suggest something like this:

1 2 3 4

for file in $lge_missing_files; do      mnt_location=$( find /mnt -name $( basename $ file ))      cp $mnt_location vendor /lge/hammerhead/proprietary/ done

And then likewise for the Qualcomm files, replacing lge for qcom.

ALRIGHT. So once we have obtained the files, we need to add them to the build system.

To do this, you need to add PRODUCT_COPY_FILES rules for each of these additional files, so that they get included in the eventual Android phone image. An example of that is shown here, in my github project for vendor/lge/hammerhead, and here, for vendor/qcom/hammerhead.

Note that if you don’t feel like going through all of this BS, you could of course just checkout and use these projects, in lieu of running the extractor scripts for LG and Qualcomm:

1 2 3

rm -r -f vendor /lge/hammerhead vendor /qcom/hammerhead git clone https: //github .com /jamesonwilliams/vendor_lge_hammerhead .git vendor /lge/hammerhead git clone https: //github .com /jamesonwilliams/vendor_qcom_hammerhead .git vendor /qcom/hammerhead

The last, and critical step, is to modify the device project, so that these vendor files are used (ref: git commit):

1	sed -i '/^PRODUCT_RESTRICT_VENDOR_FILES/s/true/false/' device /lge/hammerhead/full_hammerhead .mk

Obtain the Google Proprietary Apps

Now, usually, RootzWiki posts the Google Apps update packages here, and with a little finagling, you can adapt the updater-script into makefile rules for the Android Build System. Unfortunately, at time of writing, RootzWiki has not provided an update package for KitKat.

The most mature bundling of the Google Apps I have found for Kit Kat so far is from the Paranoid Andorid crew, as mentioned on this post.

The creation of my vendor/google/gapps project from this file is sort of outside the scope of this page, but I will mention a few of the main points.

Inspiration was taken from jpuderer‘s vendor-aospplus project.

Module rules and product copy file rules were created from scratch, for each of the proprietary files found in the Paranoid Android package.

These rules were further developed to include packages like Chrome, and to override packages that are included in AOSP but not in the default factory image. (A very noticable example is that the new Google Home launcher overrides the old Launcher3.)

In short, to include the Google apps, you need to checkout this project:

1 2	mkdir -p vendor /google git clone https: //github .com /jamesonwilliams/vendor_google_gapps .git vendor /google/gapps

And add rules to vendor/lge/hammerhead, so that the makefiles get included in the build:

1 2 3 4 5 6 7

cat >> vendor /lge/hammerhead/BoardConfigVendor .mk <<- EOF -include vendor /google/gapps/BoardConfigPartial .mk EOF   cat >> vendor /lge/hammerhead/device-vendor .mk <<- EOF $(call inherit-product- if -exists, vendor /google/gapps/device-partial .mk) EOF

(Ref: github commit.)

Including the Kernel Sources

By default, the AOSP image for hammerhead uses a prebuilt kernel binary, specifically device/lge/hammerhead-kernel/zImage-dtb. In order to build the kernel from source, we need to do a few things:

1. Get the correct version of the kernel source;
2. Adapt the AndroidKernel.mk for an in-tree build;
3. Adapt the device/lge/hammerhead project, to include the new kernel.

At time of writing, the Android documentation on Building Kernels has not been updated with instructions for hammerhead. However, it’s very similar to the Nexus 4 (mako) procedure.

Get the source by:

1	git clone https: //android .googlesource.com /kernel/msm .git -b android-msm-hammerhead-3.4-kk-r1 kernel

You can verify that the commit that branch points to is the same as the stock kernel.

Now, make a few tweaks to fix the kernel build:

1 2 3 4 5

# The build fails if we try to make the modules, so remove those lines: sed -i '48,51d' kernel /AndroidKernel .mk   # Build a dtb kernel, not the default zImage: sed -i '47s,$, zImage-dtb,' kernel /AndroidKernel .mk

Finally, we need to modify the device project.

This is a bit more involved, but you can see the patch needed in my github project.

Just Build the Thing ™

Alright. All that above was stuff I had to do. But if you had to do it everytime, you’d probably put a shotgun to your face. Fortunately, I’ve uploaded all the miscellaneous bits and pieces to github repositories, and linked them all together with my own manifest.

In short, just grab the working tree by doing this:

1 2	repo init -u git: //github .com /jamesonwilliams/platform_manifest .git -b android-4.4_r1.1 repo sync

So, you can just do that instead.

All you need to do now is build the tree:

1 2 3 4

. build /envsetup .sh lunch aosp_hammerhead-userdebug make clean make updatepackage # -j10

Deploy the thing

After the build (successfully) completes, you’ll be left with an update image package here:

1 2	UPDATE_PACKAGE= "$OUT/$TARGET_PRODUCT-img-$TARGET_BUILD_VARIANT.$USER.zip" echo $UPDATE_PACKAGE

Make sure your hammerhead device has USB debugging enabled. (If you need help with this, YouTube can help. Like This video.)

Enter the bootloader and unlock the device:

1 2	adb reboot-bootloader fastboot oem unlock

Lastly, flash the device, and reboot it:

1 2	fastboot -w update $UPDATE_PACKAGE fastboot continue

Errata

Technically speaking, android-4.4_r1 (KRT16M) is the documented tag for hammerhead, while I have used android-4.4_r1.1 (KRT16O), here. As per the Google release announcement, the only difference is that this release includes also support for the Nexus 4, Nexus 7, and Nexus 10. So, it’s more convenient to use that tag, if you’re ultimately supporting the full range of devices.