Setting Up & Building CyanogenMod for an HTC myTouch 4G

Operating System

If you have a linux box or virtual machine to use, you may skip this section. However it may be worthwhile to double check that the configuration is correct for your machine.

If you're running Windows, you can either: get a separate linux machine or create a virtual machine. Windows is not currently supported for building 
The latter option is available to UTEP students with VMWare - a virtual box application. It can be downloaded here:
  • Note: you need to create an account at the above link, which is a two step process: 1)request an account by clicking on "Sign In" > "Register" > "Request an Account". 2) After an admin approves the request, an account can be registered via its username.
  • Notice that certain types of unix/linux systems are suggested here to maximize compatibility. Ubuntu 10.04 (Lucid Lynx) is the suggested choice, isos of the 64bit (amd64) desktop version can be found here. Look for "ubuntu-10.04.3-desktop-amd64.iso".

Ports for XServer access to VM (Optional)

By default, the windows firewall blocks all access to ports created for VMs. To allow connections to a VM host, there is a workaround that we made here. Not doing this portion will prevent X servers and other local ssh connections to the VM.

Tutorials that already exist about Build environments and downloading source code

It would be worth your while to read over the following pages if you'd like. The majority of their content has been assimilated into this tutorial (I also corrected some info that was out of order or just missing from one or the other).
Please note that the following set of pages is currently device dependent on the Samsung Galaxy Nexus, although similar pages could be found for other phone models.
Again, I've included the relevant info from these pages into this tutorial; the above pages differ or omit some points, which I will try to combine properly.

The Tutorial

I have divided the following tutorial up into several sections, each of which with some bold header in a bold black font. Please read all of the content within each section before running any of the commands listed there, as some commands have circumstantial info that you may need to know before running the command. There will be more warnings along the way - don’t worry, though, I tried to group as much related info as necessary to get you through the process.

What you’ll need

  • A HTC myTouch 4G

  • A relatively recent computer (Linux, OS X, or Windows) w/a reasonable amount of RAM and storage. The less RAM you have, the longer the build will take. Using SSDs results in faster builds than traditional hard drives.

  • A micro USB cable

  • A decent Internet connection & reliable electricity :)

  • Some familiarity with basic Android operation and terminology. It would help if you’ve installed custom roms on other devices and are familiar with what a recovery image such as ClockworkMod is, for example. It may also be useful to know some basic command line concepts such as cd for “change directory”, the concept of directory hierarchies, that in Linux they are separated by /, etc.

Windows Setup

Find the following files with the search engine of your choice (seriously though, just Google it).

  1. Windows' MTP porting kit aka Media Transfer Protocol porting kit

    • download it straight from microsoft
      Note: Windows’ MTP porting kit requires a valid version of windows in order to be downloaded. In case you don’t have a valid copy of Windows, please talk to Gabriel about downloading it from an “alternate source”.

  2. latest version of "samsung usb drivers for mobile phones"

    • download it from any trusted file server

  3. pdaneta302x64.exe

Linux Basic Setup

A helpful Note: Try to keep just one terminal session, as variables are created as part of the build process; so closing a terminal may include destroying some temporary variables used by scripts within the build process. That being said, open up a terminal with Ctrl+Alt+T (on Ubuntu) and enter the following:

$ sudo apt-get install ia32-libs

Create the Directories

Note: The directory structure used when building with CyanogenMod is very fragile, so follow these directions closely, or you may end up voiding the scripts you will be running later.


You will need to set up some directories in your build environment.

To create them:

$ mkdir -p ~/bin $ mkdir -p ~/android/system


Install ADT

Download the latest ADT package for the Android SDK here:

http://developer.android.com/sdk/index.html

Select the option near the bottom of the page to “Download for other platforms” and select the appropriate version for linux. If you are using windows, it’s suggested that you also install the sdk on windows as well. The site contains installation instructions here:

http://developer.android.com/sdk/installing/bundle.html

However, the instructions above boil down to, ‘unzip the ADT bundle into the directory of your choice; be sure to remember (i.e., write down) the directory where you unzip ADT into.


Include

    ~/bin

and

    sdk/platform-tools

in your environment path (requires a restart for the path to reset). Also, make sure adb and fastboot work from the path with the following command:

$ adb devices


If you receive an adb command not found message, you have not set up your path correctly. This can be verified by entering the following in the terminal:

$ echo $PATH

You should NOT see the folders ~/bin and the path to your ADT package within the printed string. If you do see the folders within the string, try running the following command again:

$ sudo apt get install ia32-libs


If the PATH is indeed missing the folders mentioned above, you can:

  • set the path temporarily with the following command: $ export PATH=$PATH:~/bin:/path/to/the/ADT/folder 
  • Or add the line above this one (without the prompt symbol $) to the .bashrc file and restart the terminal. If the path still doesn't include the correct folders, try restarting your linux machine.

Get java from the correct repo

Orcale/Sun's java has to be used, which is not the default java used. You have to add their repository to the apt-get repos and download it from them. Back in your terminal, run the following:

$ sudo add-apt-repository ppa:webupd8team/java

$ sudo apt-get update

$ sudo apt-get install oracle-java6-installer

                       

Check the java version with "java -version". It should return:

java version "1.6.0_45"

Java(TM) SE Runtime Environment (build 1.6.0_45-b06)

Java HotSpot(TM) 64-Bit Server VM (build 20.45-b01, mixed mode)


You will also need the following programs:

  • Python 2.6 -- 2.7, which you can download from python.org

  • GNU Make 3.81 -- 3.82, which you can download from gnu.org

Note: these two should be installed into Ubuntu by default, and can be verified with the following commands, respectively:

$ python --version

$ make --version

Some more applications and setup:

Run the following commands:

$ sudo apt-get install git-core gnupg flex bison gperf build-essential zip curl zlib1g-dev libc6-dev lib32ncurses5-dev ia32-libs x11proto-core-dev libx11-dev lib32readline5-dev lib32z-dev libgl1-mesa-dev g++-multilib mingw32 tofrodos python-markdown libxml2-utils xsltproc

                                                                                           

$ sudo apt-get install git-core gnupg flex bison gperf libsdl1.2-dev libesd0-dev libwxgtk2.8-dev squashfs-tools build-essential zip curl libncurses5-dev zlib1g-dev openjdk-6-jre openjdk-6-jdk pngcrush schedtool libxml2 libxml2-utils xsltproc          


$ sudo apt-get install g++-multilib lib32z1-dev lib32ncurses5-dev lib32readline-gplv2-dev gcc-multilib

                            OR if that fails,

$ sudo apt-get install g++-multilib lib32z1-dev lib32ncurses5-dev libreadline-dev gcc-multilib


Put the following in your .bashrc or equivalent.

export USE_CCACHE=1


After installing git, your username and email should be set with the following commands:

  • $ git config --global user.name "User name"

  • $ git config --global user.email user@example.com

Linux and Android USB connections

Under GNU/linux systems (and specifically under Ubuntu systems), regular users can't directly access USB devices by default. The system needs to be configured to allow such access. The recommended approach is to create a file /etc/udev/rules.d/51-android.rules (as the root user) and to copy the following lines in it. <username> must be replaced by the actual username of the user who is authorized to access the phones over USB.

# adb protocol on passion (Nexus One)

SUBSYSTEM=="usb", ATTR{idVendor}=="18d1", ATTR{idProduct}=="4e12", MODE="0600", OWNER="<username>"

# fastboot protocol on passion (Nexus One)

SUBSYSTEM=="usb", ATTR{idVendor}=="0bb4", ATTR{idProduct}=="0fff", MODE="0600", OWNER="<username>"

# adb protocol on crespo/crespo4g (Nexus S)

SUBSYSTEM=="usb", ATTR{idVendor}=="18d1", ATTR{idProduct}=="4e22", MODE="0600", OWNER="<username>"

# fastboot protocol on crespo/crespo4g (Nexus S)

SUBSYSTEM=="usb", ATTR{idVendor}=="18d1", ATTR{idProduct}=="4e20", MODE="0600", OWNER="<username>"

# adb protocol on stingray/wingray (Xoom)

SUBSYSTEM=="usb", ATTR{idVendor}=="22b8", ATTR{idProduct}=="70a9", MODE="0600", OWNER="<username>"

# fastboot protocol on stingray/wingray (Xoom)

SUBSYSTEM=="usb", ATTR{idVendor}=="18d1", ATTR{idProduct}=="708c", MODE="0600", OWNER="<username>"

# adb protocol on maguro/toro (Galaxy Nexus)

SUBSYSTEM=="usb", ATTR{idVendor}=="04e8", ATTR{idProduct}=="6860", MODE="0600", OWNER="<username>"

# fastboot protocol on maguro/toro (Galaxy Nexus)

SUBSYSTEM=="usb", ATTR{idVendor}=="18d1", ATTR{idProduct}=="4e30", MODE="0600", OWNER="<username>"

# adb protocol on panda (PandaBoard)

SUBSYSTEM=="usb", ATTR{idVendor}=="0451", ATTR{idProduct}=="d101", MODE="0600", OWNER="<username>"

# fastboot protocol on panda (PandaBoard)

SUBSYSTEM=="usb", ATTR{idVendor}=="0451", ATTR{idProduct}=="d022", MODE="0600", OWNER="<username>"

# usbboot protocol on panda (PandaBoard)

SUBSYSTEM=="usb", ATTR{idVendor}=="0451", ATTR{idProduct}=="d00f", MODE="0600", OWNER="<username>"

# usbboot protocol on panda (PandaBoard ES)

SUBSYSTEM=="usb", ATTR{idVendor}=="0451", ATTR{idProduct}=="d010", MODE="0600", OWNER="<username>"

# adb protocol on grouper/tilapia (Nexus 7)

SUBSYSTEM=="usb", ATTR{idVendor}=="18d1", ATTR{idProduct}=="4e42", MODE="0600", OWNER="<username>"

# fastboot protocol on grouper/tilapia (Nexus 7)

SUBSYSTEM=="usb", ATTR{idVendor}=="18d1", ATTR{idProduct}=="4e40", MODE="0600", OWNER="<username>"

# adb protocol on manta (Nexus 10)

SUBSYSTEM=="usb", ATTR{idVendor}=="18d1", ATTR{idProduct}=="4ee2", MODE="0600", OWNER="<username>"

# fastboot protocol on manta (Nexus 10)

SUBSYSTEM=="usb", ATTR{idVendor}=="18d1", ATTR{idProduct}=="4ee0", MODE="0600", OWNER="<username>"

# fastboot protocol on glacier (HTC myTouch 4G) SUBSYSTEM=="usb", ATTR{idVendor}=="0bb4", ATTR{idProduct}=="0c96", MODE="0600", OWNER="<username>"

Those new rules take effect the next time a device is plugged in. It might therefore be necessary to unplug the device and plug it back into the computer. This is known to work on both Ubuntu Hardy Heron (8.04.x LTS) and Lucid Lynx (10.04.x LTS). Other versions of Ubuntu or other variants of GNU/linux might require different configurations.

(To check if the new rules worked, try the command 'adb devices' and you should get the phone's serial number. If you get '???????? no permissions', then try sudo service udev restart).

Final Checks

Before moving forward, verify the following two:

$ echo $USE_CCACHE

The above should return the number 1 (one).

$ echo $PATH

The above should return a string including ~/bin and your path to the ADT bundle.


If either command does not display the desired result:

  1. Restart your terminal. The modifications to system variables and the path are applied at the start of a terminal, so if you haven't restarted it in a while, do so.
  2. Make sure that the 'export USE_CCACHE=1' and path modifications mentioned earlier have been completed.

Unlocking the phone

Congratulations on completing the initial setup before building. Now we can focus on the actual build process.... in a minute. First the phone has to be unlocked so we can get access to internal files and eventually to replace the stock recovery (if it’s still there).


HTC has allowed for their bootloader to be unlocked, so we will use the HTCdev tool to unlock the myTouch 4G. Go to http://www.htcdev.com/bootloader/, 

select the myTouch 4G from the device drop down and follow the instructions provided.

Note: You will need to sign in or create an account with them (it's free).

Install repo

Enter the following to download the "repo" binary and make it executable (runnable):

$ curl https://dl-ssl.google.com/dl/googlesource/git-repo/repo > ~/bin/repo $ chmod a+x ~/bin/repo


Initialize the repo

Enter the following to initialize the repository:

$ cd ~/android/system/
$ repo init -u git://github.com/
robustUTEP/android.git -b gb-release-7.2

The argument after -b is the branch to be downloaded. To see which branches are available from Robust, please see:

https://github.com/robustUTEP/android/branches


Note: Ubuntu 10.04's repositories include only an earlier version of git. If you see some error about needing a newer version, then you will need to add some custom repositories to get it to work. So if repo init fails:

    $ sudo add-apt-repository ppa:git-core/ppa

    $ sudo apt-get update

    $ sudo apt-get install git


To start the download of all the source code to your computer:

$ repo sync

This command will run for some time.


*Optional Tip:

I created an executable script within my bin directory that would play a sound which I named myAlert  (I installed mpg123 and I downloaded an mp3 of an alert    sound that I fancied, the script just combines the two into a single command). In addition to the repo, and upcoming breakfast, and brunch commands, I added the following to each command so my alert noise would play, alarming me to the fact that the long process has finally completed:

$ <comand>; myAlert

i.e.:

$ repo sync; myAlert

This is completely optional, however I felt a bell of some sort really helps when you’re probably AFK after being bored by the exciting-as-paint-drying action of the aforementioned commands.


A Note about Errors after this point

As I mentioned earlier, the directory hierarchy for building CyanogenMod is very fragile. Executing repo sync in any folder besides ~/android/system will cause scripts downloaded and run after this point to call incorrect commands to non-existent folders. It is even possible to continue and build without completing some of the following, BUT THAT WILL LEAVE YOU WITH AN INVALID OPERATING SYSTEM ON YOUR PHONE. (Sorry for the caps, but it needs to be said) Basically you'll have a phone that doesn't work because the wifi and wireless data drivers weren't initialized correctly. 


In Short, follow the instructions here exactly, or else your CyanogenMod builds will secretly fail, meaning you could go all the way to installing your build before realizing your error came from e.g. step 2.


After you've downloaded the android source code:

The suggested cache size is 50-100GB. You will need to run the following command once you have downloaded the source code:

$ prebuilts/misc/linux-x86/ccache/ccache -M 50G


When building Ice Cream Sandwich (4.0.x) or older, ccache is in a different location:

$ prebuilt/linux-x86/ccache/ccache -M 50G


This setting is stored in the CCACHE_DIR and is persistent.


Get the prebuilt Rom Manager

Next,

$ cd ~/android/system/vendor/cyanogen

then enter:

$ ./get-rommanager

You won't see any confirmation- just another prompt. But this should cause Rom Manager apps to be loaded and installed into the source code. Once completed, this does not need to be done again.

Pull Changes

For some reason repo sync downloads the source code from CyanogenMod without the changes to dalvik. To obtain the changes do:
$ cd ~/android/system/dalvik
$ git pull git://github.com/robustUTEP/android gb-release-7.2

Starting the Build (finally!)

After the source downloads, ensure you are in the root of the source code (cd ~/android/system), then type:

$ source build/envsetup.sh $ lunch

You should see a list of devices, including something like cm_glacier-userdebug. Select it by typing its number. It is possible that lunch does not display your device. In that case try :

lunch cyanogen_glacier-userdebug or $ lunch full_glacier-userdebug


(Remember to use '; myAlert' with the lunch and brunch commands so you can be alerted when these long commands complete)

If you want to know more about what "$ source build/envsetup.sh" does or simply want to know

more about the breakfast, brunch and lunch commands, you can head over to

the Envsetup_help page:

http://wiki.cyanogenmod.org/w/Envsetup_help

Extract Proprietary Blobs

Now ensure that your Galaxy Nexus (GSM) is connected to your computer via the USB cable and that you are in the ~/android/system/device/htc/glacier directory (you can cd ~/android/system/device/htc/glacierif necessary). Then run the extract-files.sh script:

$ ./extract-files.sh

You should see the proprietary files (aka “blobs”) get pulled from the device and moved to the right place in the vendor directory. If you see errors about adb being unable to pull the files, adb may not be in the path of execution. If this is the case, see the adb page for suggestions for dealing with "command not found" errors.

Note:

Your device should already be running the branch of CyanogenMod you wish to build your own version of for the extract-files.sh script to function properly (or stock). If you are savvy enough to pull the files yourself off the device by examining the script, you may do that as well without flashing CyanogenMod first.

Note:

It’s important that these proprietary files are properly extracted and moved to the vendor directory. Without them, CyanogenMod will build without error, but you’ll be missing important functionality, such as the ability to see anything!

Build, Build, Build

Let's continue building! Ensure you are in the root of the source code (cd ~/android/system), then type:

$ croot $ brunch glacier


Helpful Tip: If the build doesn't start, try lunch and choose your device from the menu. If that doesn't work, try breakfast and choose from the menu. The command make glacier should then work.


Helpful Tip: A second, bonus tip! If you get a command not found error for croot or brunch or lunch, be sure you’ve done the “ . build/envsetup.sh” command in this Terminal session from the ~/android/system directory.


Once the Build is done

Assuming the build completed without error (it will be obvious when it finishes), type:

$ cd $OUT

in the same terminal window that you did the build. Here you’ll find all the files that were created. The stuff that will go in /system is in a folder called system. The stuff that will become your ramdisk is in a folder called root. And your kernel is called... kernel.

But that’s all just background info. The two files we are interested in are (1) recovery.img, which contains ClockworkMod recovery, and (2) cm-[something].zip, which contains CyanogenMod. It should look something like the following, possibly even including your username:

cm-7-20130709-UNOFFICIAL-glacier.zip


Push the update files to the phone

With the phone connected to the computer, and while in the $OUT directory, run the following:

$ adb push cm-*.zip /sdcard/

That command should work (take note of the dash in 'cm-' as using an underscore will yield a different zip file that can't be used to install CM on your phone), however, if that does not work, replace the wild card (*) with the actual file name from the out directory.


At this point, you also want to push the correct Google Apps file to the phone as well. Be sure to download the correct version of google apps; a convenient table that matches CyanogenMod versions with the correct google apps can be found here (at rootzwiki).

To download the file, you can get it here (ignore the table at the top of the page and download the correct file from the bin found below the table according to the version needed according to the rootzwiki link above).


While in the folder where the gapps-[something].zip file resides, use the following command, again, replacing the wild card with the correct file name if necessary:

$ adb push gapps*.zip /sdcard/


Installing ClockWorkMod (CWM) Recovery

You can skip to the next section about installing CyanogenMod if your phone already has ClockWorkMod or some other custom recovery flashed.

You can use fastboot to install your recovery image to the device.

  1. Connect the Galaxy Nexus (GSM) to the computer via USB.

  2. Make sure the fastboot binary is in your PATH or that you place the downloaded image in the same directory as fastboot.

  3. Open a terminal on your PC and reboot the device into fastboot mode by typing adb reboot bootloader or by using the hardware key combination.

  4. Once the device is in fastboot mode, verify your PC sees the device by typing fastboot devices

    • If you don't see your device serial number, and instead see "<waiting for device>", fastboot is not configured properly on your machine. See fastboot documentation for more info.

  5. Flash ClockworkMod Recovery onto your device by entering the following command: fastboot flash recovery your_recovery_image.img where the latter part is the name of the file you downloaded.

  6. Once the flash completes successfully, reboot the device into recovery to verify the installation. This can be done by typing fastboot boot your_recovery_image.img.

    • Note: Some ROMs overwrite recovery at boot time so if you do not plan to immediately boot into recovery to install CyanogenMod, please be aware that this may overwrite your custom recovery with the stock one. This shouldn’t be a problem if you’ve pushed the install files in the previous section.

Installing CyanogenMod via CWM recovery mode

You should now be in the ClockWorkMod recovery menu. Use the volume buttons to move up and down and use the power button to select options (although, you probably already knew that).

  1. From this menu, select backup and restore to create a backup of your phone before installing a new build (just in case). This should be a mandatory step in the process, unless you're absolutely sure the build will work (or if you just like to live dangerously).

  2. Select the option to wipe data/factory reset.

  3. Select install zip from sdcard.

  4. Select choose zip from sdcard.

  5. Select the CyanogenMod file you placed on the sdcard. You will then need to then confirm that you do wish to flash this file.

  6. Repeat steps 4 and 5 but with the google apps update package that you pushed to the phone.

  7. Once the installation has finished, return back to the main menu, and select the reboot system now option. The device should now boot into CyanogenMod.


If the phone does not reboot to CyanogenMod and hangs at any of the boot splash screens, there is a problem. Remove the battery and enter fastboot mode by holding down the volume down and power button until the phone vibrates. In fastboot mode, enter recovery mode by selecting the option using the volume buttons. Select backup and restore again and restore the backup image that you created in step one from this section (you did do step one, didn't you?). Try rebooting the phone at this point to make sure it still works, then return to recovery mode and try installing CyanogenMod with the instructions above but skip step 6. If this still doesn't work, there is a problem with the build - sorry, better luck next time.

If the phone boots but keeps displaying a popup that explains that the android keyboard has stopped working (if you can't read the popup from disappearing so quickly, then this applies to you as well), then you have the wrong version of Google apps installed. With the phone on, go to Settings > About Phone and double check which version of android you have built and take note of it. Then please return to the section above about downloading Google apps and double check you have the correct version. Try running the steps above again. (The previous paragraph explains how to enter recovery mode from the phone being turned off).

Comments