How to

Retrieving and building a patch submission already on Gerrit

Let’s say you’d like to try this new LCD option in the Settings app. (This is just an example of a proposed commit I found quickly that wasn’t yet merged. Since being added to this wiki it has been merged, but read anyway to get the idea– we’re going to pretend it’s still under review).

To add this patch to your local build source code:

Using repopick

repopick is a new command as of November, 2014 that makes adding proposed patches almost too easy.

If you type repopick -h you’ll get a list of supported commands, such as the ability to do multiple patches or ranges of patches in a single command.

Here’s all you do:

1. Note the URL of the proposed commit. In the above case, it’s http://review.cyanogenmod.org/#/c/85052/ That number, 85052 will come in handy in a second.
2. Go to the source code. cd to android/system.
3. Run Envsetup . build/envsetup.sh to add the function to your environment.
4. Now just type the following command: repopick 85052 The patch should be applied automatically.
5. Go ahead and build. When you’re done, you’ll hopefully have the feature you wanted.
6. If it worked alright, go sign up for Gerrit and give a +1 vote to the proposed contribution.

Manually applying the commit

Alternately, you can do the commit “manually” (that is, the OLD way of doing it):

1. Where it says Download in the middle of the screen, there’s some instructions for you to highlight and copy. In this case, it looks like “git fetch http://review.cyanogenmod.org/CyanogenMod/android_frameworks_base refs/changes/31/11131/3 && git cherry-pick FETCH_HEAD” Or, you can click the little icon to the right of those instructions and the same text will automatically go to your copy buffer.
2. This patch affects android_packages_apps_Settings (as you can see at the top of the gerrit description), so cd packages/apps/Settings.
3. Now paste the command. You’ve just added the proposed change to your copy of the source code.
4. Go ahead and build. When you’re done, you’ll hopefully have the feature you wanted.
5. If it worked alright, go sign up for Gerrit and give a +1 vote to the proposed contribution.

Being able to try cutting-edge features and improvements now is in your hands. You don’t have to wait for a nightly build any more. You don’t even need to wait for the code to be ACCEPTED into CyanogenMod! You can help test it and get these features before anyone else even knows about them. Just keep checking Gerrit.

Submitting to Gerrit

1. If you have not already successfully downloaded the source and generated a build of CyanogenMod, make sure you are familiar with these steps. Information on doing a build is available elsewhere on this wiki.
2. Setup an account on Gerrit, you can register at review.cyanogenmod.org
3. Make sure your local git username matches with your Gerrit username, Gerrit username needs to be configure in the Gerrit portal under settings -> HTTP Password

   git config --global review.review.cyanogenmod.org.username "gerrit username"

4. If you already have SSH keys set up (e.g. for Github), skip the following steps
5. Generate SSH keys,^[1] and copy/paste to your Gerrit account:

   ssh-keygen -t rsa -C "[email protected]"

6. Make sure your keys are added to your ssh agent:

   eval `ssh-agent -s`

   ssh-add ~/.ssh/id_rsa

   ssh-add

Uploading your changes

First, you need to start a topic branch. This ‘branch’ holds the changes you make to the files on your computer that you will ultimately send to the CyanogenMod servers for review. Create your topic branch:

repo start <branch name> <project path>

Note: This starts a new branch called ‘<branch name>’ in the ‘<project path>’ project. Replace <project path> with the path of your target repository instead.

Now, you can cd to the project (directory) that contains the file(s) you want to edit:

cd path/to/project

Now you can make your changes. Make sure you do not edit any files before you run repo start, or your changes will happen on a different branch and will not be tracked correctly.

After you make your changes, you can commit them just as you would normally:

git add <file you edited>

git commit

croot (Same as moving to top/root of tree using cd)

Now you can upload your changes to the CyanogenMod server:

repo upload <project path>

That’s it! Your change will be reviewed and may be accepted or rejected.

See #Example_cases below for an example.

Submitting Patch Sets

Frequently your submitted patch has issues or errors, which are noted in the code review, so you will want to resolve them. Sometimes it’s just tabs instead of spaces or typos in strings and variable names. To avoid some formal mistakes, make sure you’re familiar with the android code style. For Eclipse users, just follow the instructions in development/ide/eclipse/README.importing-to-eclipse.txt.

Before you edit those files, type in git branch to make sure you are on the correct branch. If you are not in the correct branch or in no branch at all, type in git checkout [branchname] to switch to the correct branch. Now you can edit the files. After you made your changes, do the usual git status and notice that git diff will only show you the changes you just made. Once you are satisfied, you can prepare the upload.

Type in git commit --amend. This will open an editor with your initial commit message. Make sure you have previously added the files that you’ve modified by using git add. The default editor is vi. This can be changed by the EDITOR environment variable to any editor you like. You can also change the commit message if you want to, but make sure the last two lines stay as are. They contain the initial commit ID and a blank line. With this id, Gerrit will detect your upload as a patch set and not as a new patch.

You can do git log and git status again. Notice how Git handles your initial commit and the commit using –amend as one patch. Same for git show. It will show you all the changes, your initial patch & the patch set you just committed, as one patch.

Now you can submit your patch set to your initial patch with repo upload <project name>.

Example cases

Edit InputDevice.java

Add AWEXT Support

Common Commands

See Git Immersion for more information

Repo

repo abandon <branch name>

To abandon any changes (commits) that have not been uploaded

repo start <branch> <project>

Starts repo listening for changes through git

repo upload <project name>

Uploads committed changes to the remote review server

Git

git add <file name>

stages a file that has been changed or added

git commit -m “comment”

commits a change

git reset HEAD <file name>

unstage a file

git revert HEAD

undo the last commit

git status

See the status of a project

Troubleshooting

^[1] If you get Permission denied (publickey). error, and you’re sure that everything is right, try using a DSA key instead of RSA.

ssh-keygen -t dsa -C "<email>@<server>.<domain>"

Getting your submission reviewed/merged

All submitted patches go through a code review process prior to merger. In addition to getting reviewed by your peers, selected project members have the capability to merge your code into CyanogenMod (to make sure they get informed, add one or more responsible reviewers to your commit). To see a breakdown of who is responsible for the various aspects of CM, please see the Gerrit Reviewers list.

Resources

• Git Immersion
• Using git and repo
• Gerrit Documentation
• Github Organization

Navigating through the menus

Different devices have different numbers of physical buttons– power buttons, menu buttons, home buttons, back buttons, volume keys, etc.

Using Physical Keys and Buttons

Typically, the volume keys are used to move up and down the menu and, if available, a home button is used to select the item. If the home button does not exist, the power button is frequently used to make the selection. On devices in which there is a home button, the power button is usually used to go “back a menu”. On devices without a home button, there is usually a “++++Go Back++++” option at the bottom of the list.

Touch options

On newer versions of ClockworkMod recovery, menu items can be selected simply by touching on the item with a finger.

Backup and Restore Your Device

Making a backup

Before you begin, ensure you have sufficient space for your backup.

Make sure that you do not have a password or screen lock pin when you backup your data

1. Boot into Recovery Mode
2. Select Backup and Restore
3. Select Backup
4. Follow on screen directions to complete the backup.

Restoring a backup

1. Boot into Recovery Mode
2. Select Backup and Restore
3. Select Restore (or Advanced restore if you wish to restore only a portion of your device.)
4. Follow on screen directions to complete the backup.
5. Select your ‘Device-ID’ from the list (You will most likely only have one device listed)
6. Select the backup you want to restore (Latest should be last on list)
7. Follow on screen directions to complete
8. Wait for it to complete.

Additional Commands

Most commands are fairly self-explanatory. Here are a few, with some definitions.

• reboot system now — this will reboot the system into its normal boot mode
• install zip from sdcard — This is used to flash a .zip file, located on the /sdcard partition, which can be used to install new versions of CyanogenMod among other things.
• apply update from sdcard –Installs the update.zip located in the root of your SD card
• wipe data/factory reset — Obvious – clears everything (except your SD card, hopefully)
• wipe cache partition — erases and formats /cache
  • apply /sdcard/update.zip — Installs the update.zip located in the root of your SD card
  • choose zip from sdcard — Lets you browse for and pick the update or installation .zip file
  • toggle signature verification — Turns zip package signature requirement on/off
  • toggle script asserts
  • advanced restore — Allows you to select a backup, as well as select which portions of the backup to restore (such as the /boot, /system, /data, /cache, /sd-ext)
• mounts and storage — this allows you to mount or unmount the various partitions. Advanced users can access files on mounted partitions through adb.
  • unmount /cache
  • mount /data
  • unmount /sdcard
  • mount /system
  • mount /sd-ext
  • format /cache
  • format /data
  • format /sdcard
  • format /system
  • format /sd-ext
  • mount USB storage
• advanced — more advanced options
  • reboot recovery — reboot the device back into recovery mode
  • reboot bootloader — reboot the device to the bootloader
  • power off — power down the device
  • wipe dalvik cache — wipe temporary files used by the Dalvik virtual machine. The Dalvik virtual machine is the ‘sandboxed environment’ which runs Android apps written in Java. This is generally safe to perform.
  • report error — copies recovery.log to /sdcard/clockworkmod/. This log can then be submitted to developers using the ROM Manager application.
  • key test — allows you to test your hardware keys on the device
  • show log — outputs the current recovery.log to the screen
  • partition </path> — allows you to create an ext3 or ext4 partition on your SD card. Allowed sizes range from 128M to 4096M.
  • toggle loki support — enables flashing kernels on some Samsung devices
  • wipe battery stats — if you are having misreported battery strength, it may be useful to remove the battery stats history file [this feature was removed beginning with version 6.0.2.0 due to user misunderstanding over its use]
  • fix permissions — resets system permissions back to their default values [this feature was removed beginning with version 6.0.3.5 due to its placebo effect as a cure-all]

Special Notes

Unofficials: Some devices do not have an official ClockworkMod recovery available. If this is the case for your device, you can often find unofficial recoveries on one of the various Android forum websites. Unofficial simply means they are not maintained by CyanogenMod and assistance may not be available by CyanogenMod team members. Aside from ClockworkMod, other unofficial recoveries include, but are not limited to TWRP and Philz-Touch.

Encryption: ClockworkMod does not currently support reading encrypted partitions. It therefore cannot create backups of an encrypted /data partition and will report an error when attempting to perform a full backup. If you would like to keep using ClockworkMod, the only option is to format /data, which will wipe all of your apps and settings. Alternatively, TWRP supports reading from and writing to encrypted /data partitions.

A bit about logcat

So for all of you who don’t know about adb logcat, it’s probably time we talked about it.

When Android is running, it’s generating all kinds of system messages. You see, programmers/developers can optionally output status information (or errors or debugging notes) in real-time to a system log, and Android itself sends all kinds of useful information out that way.

But if there’s a running log going on at all times, how do you see it?

If you’re connected via ADB (via a USB cable or whatever), try typing adb logcat into your computer. The output to your terminal window, which can be interrupted with ^C (control + C), is a real-time look at Android’s operation.

So, let’s say you’re experiencing a boot loop and want to get an idea of what’s going on “under the hood”. It can’t hurt to peek with adb logcat. Even if it just looks like gobbledygook, you can copy and paste the output (usually the errors will be obvious if you sit down and look– stuff like “ERROR!!!!!” may appear) to a site like pastebin.com (although make sure that you’re not pasting personal information such as local network addresses or anything sensitive, which occasionally will appear in the log). That way, you can show people the problem (via a link) for further discussion, debugging, etc.

Anyway, from now on– instead of just saying “Help! I’m bootlooping!“, maybe say “Help! I’m bootlooping, and here’s a link to the logcat!”

Bonus Command!: If you’re using Linux or OS X and want to view a file from the terminal, but don’t like how cat filename.txt spews the contents at you nonstop, try using more filename.txt instead. (I’ll leave it to you to figure how it works.)

Original Source: http://forum.xda-developers.com/showpost.php?p=21353661&postcount=1570

Advanced usage

Filtering

By priority

adb logcat offers extra functionality to filter logs based on priority. The usage is adb logcat *:# where # is one of the following.

 V    Verbose (show all possibly useless logs, default level)
 D    Debug (show all reasonable debug logs)
 I    Info (show expected logs for regular usage)
 W    Warn (show possible issues that are not yet errors)
 E    Error (show issues that have caused errors)
 F    Fatal (show issues that are fatal to runtime and will often result in rebooting)

All priorities automatically include higher priorities, so adb logcat *:W will show warnings, errors and fatal errors. When an app crashes, for example, you can usually use adb logcat *:E to see the cause of the issue without having to look through irrelevant debug logging. However, when providing logs to developers make sure to include all logging (without any filtering tag) because debugging logs can often explain the error.

By Content

You can also filter by content. Let’s say you want to collect all lines of the log that mention the term “Google”. You can do this:

$ adb logcat | grep Google

This command takes the output of “logcat” (all the junk) and “pipes” it to the grep command, which is used to search for “Google” and will only return lines that include it.

If you want to make your search case-insensitive, you can just add the -i argument:

$ adb logcat | grep -i Google

This will return log lines that have “Google”, “google”, “gOoGlE” and any other combination of upper and lowercase characters.

Color

adb logcat -C can be used to show logs with color to make them easier to read when viewing.

If you are not satified with the -C parameter, other possibilities are using external color logcat scripts or writing your own.

• Colored logcat by Jeff Sharkey (Git here, Blog post here)
• logcat-color by Marshall Culpepper (Git here)

Clearing

If you find your screen is getting spammed with log messages you don’t want, but you still need verbose logging, you can use adb logcat -c to clear the log buffer. This will reset the log and only logs after the reset will be shown.

Logcat for Bugtracker

On device

This will generate a logcat on your sdcard which you can then attatch to a bug you want to report.

• Open Console Application of your choice (CM <=11.0 comes with ‘Terminal Emulator’ preinstalled; CM >=12.0 has ‘Terminal’ that you can turn on in Developer Options)
• Switch to root (type su and confirm root access) (You may have to turn on root access for apps in Developer Options)
• Type logcat -d -f /sdcard/logcat.log *:V
• Alternatively the radio buffer can be viewed with logcat -b radio

-d    makes it dump the logcat
-f    tell it where to save the log to
*:V   gets all Logs in Verbose mode

Introduction

What’s a “git“?

CyanogenMod uses a special program for storing, distributing, maintaining, and synchronizing the thousands of source code files that make up Android. The system, known as a version control system, is called git.

git was developed primarily by Linus Torvalds and is used not only by CyanogenMod, but by AOSP (Android Open Source Project– the vanilla Android source code from Google), the Linux Kernel, and countless open source projects around the world.

git allows every developer to have their own full copy (called a “git repository”) of all the source code that is used to build CyanogenMod. The code base can be easily re-synchronized with a single command so that it is always kept up-to-date. Just as important, git allows developers to easily contribute their bug fixes and enhancements back, where it may be accepted to become part of the official repository.

Because git is “decentralized”, a developer can send their changes (known in git terminology as a “commit“) not only back to CyanogenMod, but to any other person’s repository (with their permission, of course). Similarly, they can receive commits from CyanogenMod or from anyone else.

git is extremely powerful. It allows you to track the history of any files or directories over time, create instant “branches” for safely making experimental changes, add or subtract changes made by yourself or others, see where specific lines of code originated, merge your directories with other contributions, and much, much more.

Confused? Great. Keep reading.

What’s “github”?

As git has become extremely popular, several web sites have popped up to make using git super easy. One of the more popular sites, and the one that CyanogenMod uses to host its source code, is called GitHub. Github offers free git repositories for public projects.

Where can I learn how to use git?

There are many, many places online to learn about git. Each is geared to a particular audience. Some people who learn git may have had experience with other version control systems. Due to the power git offers, there are even people using git who aren’t developers; it can be used for any kind of collaborative project where you might need to track files and directories.

If you have used such non-distributed version control systems as cvs or svn, you will be delighted by this video of Linus Torvalds explaining git‘s advantages at the Google campus:

• Linus Torvalds talks about git at Google – watch this even if you know nothing about versioning systems. You won’t understand everything, but that’s okay. It’s really a must-see if you have the slightest interest in using git

One nice thing about github.com is that they do a terrific job of introducing git-related concepts through some tutorials. So if you’re new to git or github, take a look at this video:

• Github Learning Series, episode 1 — Introduction to git

Some more places to learn:

• Git Immersion – a good place to start
• git Manpage – the official git manual. Can be a little dry.
• Pro Git — a full book on using git, written by Scott Chacon and published by Apress. Available for free in several formats.
• GitRef — a helpful quick reference guide for common git commands.
• Code School — basic concepts of git version control
• Understanding git conceptually

Where are the official CyanogenMod github repositories?

Right here. These directories are the component repositories that come together to form the CyanogenMod source code.

What’s the best way to download all the CyanogenMod source code repositories from github.com to my computer?

Because there are several dozen git repositories that come together to form the full CyanogenMod source code base, there needs to be a way to keep track of all the repositories and make sure they are all in sync. That method is specific to Android, and it is called repo. repo is an Android tool used to manage all the git repositories that form Android and synchronize them (using the repo sync command) to your computer.

Rather than discuss how to use the repo command on this page in any detail, it may be best to refer you to the Build Guides on this wiki, which do walk you through downloading and using repo in the context of building CyanogenMod for your device.

Enabling Developer options

Android includes a special Developer options menu with settings relevant to advanced users and developers. Many of the options come from Android and CyanogenMod provides several additions. This menu is hidden by default, but can be activated with the following steps:

1. From Settings, select About phone (or About tablet).
2. Tap the Build number entry seven times. On the seventh tap, you will be notified that “You are now a developer.”
3. Return to Settings. Developer options should now be visible.

Enable USB debugging

The most common debugging techniques used to diagnose problems on Android are Logcat and kernel logs (dmesg). The first step to using these tools is enabling USB debugging so that you can generate and pull logs from your phone to your computer. USB debugging has a number of other uses as well, see the adb page.

To enable USB debugging:

1. Enable Developer options by following the instructions in the previous section
2. Enable System > Developers options > Android debugging

Managing superuser (root)

Beginning with CyanogenMod 12, root options are enabled from the Developer options menu. Look for the option entitled “Root access”. By default, root is disabled for security purposes. Root permissions for apps are handled by Privacy Guard in Settings. Tap an application to enable/disable root access for that application.

Content of this page is based on informations from wiki.cyanogenmod.org, under CC BY-SA 3.0 licence.

---

Should I modify (“mod”) my device?

When making the decision on whether or not to modify the software on your device, several factors come into play. Your Android device is pretty much a full computer (and if it’s a phone it has additional mobile functions), so it may help to think of it in the same way as you would consider modifying your laptop or desktop computer from its stock installation.

Pros

Common reasons to modify your device’s operating system include:

• Remove unwanted programs (“bloatware”) installed by your carrier

• Receive more frequent security updates

• Have access to the current version of Android – most carriers take months to update devices on their network to the latest version of Android, if ever. Taking control of your OS allows you to update regularly, when you feel like it’s time.

• Better performance

• Extra features

Cons

Common concerns include the following:

• Some device manufacturers or mobile providers may offer a limited or voided warranty after modifying

• It is possible that by installing a rooted operating system, you introduce new security risks. For instance, you need to be smart about the permissions you grant applications.

• Non-stock firmware could contain malicious code – which is a good argument for making sure you download custom ROMs from trusted sources, or even better, learn to build it yourself!

• Stability issues may arise when using an experimental operating system. However, for many people, CyanogenMod has proven to be more stable than many official ROMs.

Other Discussions/Articles

To read more about the pros and cons of rooting and installing custom roms, check out this article from Android Authority. For a good overview of CyanogenMod specifically, check out this article from Addictive Tips.

Why use CyanogenMod?

What’s a list of ‘why’ without some compelling reasons to entice you?

The core ideas are the same throughout our releases:

• Secure

• Light footprint

• Bloat-free

• Customizable

• Open

This translates into an abundance of features that let you truly own your phone.

• Feature List
• 

  CM Updater: Never miss an update! Our updater not only lets you have the latest releases, but you can update on your own schedule.

• 

  Privacy Guard: Control what your applications can learn about you and your contacts. Protect yourself with a simple click, or long press an app to delve deep.

• 

  Global Blacklist: Baked right into the OS is the ability to flag telemarketers, robo-callers, annoying people (yes even the in-laws) and blacklist them. Never receive another call or message from them (or maybe just ignore them for a little bit).

• 

  Quick Setting Ribbon: Embed quick toggles (and even your camera) right in your notification drawer, just one swipe away.

• 

  Quick Settings Config: Whether using the ribbon view or the larger grid view, customize the layout and order of your quick settings.

• 

  Theme: With the integrated theme engine, you can change the look and feel of the entire OS. Sports fan? Why not get a sports theme for your favorite team. Or maybe you just need a lighter overall look. Or red, green, or yellow. Endless possibilities!

• 

  Trebuchet: Not only does our custom launcher ‘Trebuchet’ allow for customizing the layout of the homescreen, it’s backed by a comprehensive, built from the ground-up theme engine. With custom theme packs, you can take your customization to a whole new level, altering window styles, icons, fonts, wallpaper, the lock screen, boot animations, and sounds!

• 

  Status Bar Behavior: Customize your status bar and unlock some additional behavior. Tap the time to quickly set an alarm or tap the date to access your calendar. Show or hide as much as you’d like.

• 

  CM Account: We built a secure, encrypted and optional account service right in. Get remote find and wipe capabilities (for free) so even if you lose your device, you still have some control.

• 

  CM File Manager: Organize, edit, and manage your files with this simple, yet powerful file manager.

• 

  Display and Lights: Control brightness, rotation, wallpapers, remote displays, notification lights, and battery lights. You decide what suits your tastes.

• 

  Profiles: Our lives are always subject to context – what’s appropriate at home may not be at work. So why aren’t our devices? With profiles you can control application, sounds and even connectivity to quickly adapt to the environment in which you are using your phone. Go one step further and set up a profile to be location aware, or use NFC to trigger a profile change.

• 

  Button Configuration: Enable additional functionality from your hardware keys, or even remap them altogether. Your choice.

• 

  Navbar: Why stop at hardware buttons? Customize the software navigation bar to your liking as well.

• 

  Lockscreen: Add quick unlock targets to access your favorite apps directly from the lockscreen. Use our custom lockscreen widget to increase your productivity. Show the weather and your calendar events without unlocking the device. Optionally display battery status or even your name and ICE information.

• 

  DSP Manager: For you audiophiles, unlock the potential of your headphones by tuning your music with our built in equalizer.

• 

  Tethering: Share your device’s data connection with your PC, tablets, friends and families with built in tethering over USB, WiFi and Bluetooth.

• 

  Developer Tools: We add a bit more for developers as well. Customize your device hostname; go wireless and use ADB over your network.

• 

  Root Access: Useful to developers and users alike, control your exposure to root applications and debugging tools.

• 

  Superuser: Manage root access to only the applications you trust, check access logs, and revoke their access when you are done.

• 

  Performance Options: Push it up to eleven and access power tools to overclock, manage device governors and more. Recommended for advanced users only.

• 

  Advanced Device controls: These options vary by device, but allow for even more control over the hardware on your phones.

• 

  SMS Rate limit: There are some bad apps out there. Enable rate limiting to get a notice if an app starts spamming bogus SMS message services to generate advertising revenue for a malicious developer. Or maybe you just have a teenager and this is perfectly normal.

Common questions

• Why flash CyanogenMod?
  • There are many reasons to consider for flashing your device. Check out our Why Mod? page for more info!
• Do I need to root my phone before installing?
  • No. You can have a rooted phone, or not. The installer doesn’t care. However, to be in a supported configuration, you need to be running a stock ROM.
• Do I need to unlock my bootloader first?
  • No, you don’t. If your bootloader is locked, we’ll unlock it for you.
• Can I install if I’m running a custom ROM?
  • Provided the installer can identify your phone correctly, it doesn’t matter which ROM you’re running. Again, to be in a fully supported configuration, you should be running a stock ROM. If you’re already running a custom ROM, you probably know what you’re doing.
• What build type of CyanogenMod is installed with the installer?
  • The installer uses a stable snapshot build unique to the installer. These are stable builds designed to provide all core features and functionality of the device.
• How do I get updates?
  • Updates are done via Settings > About phone > System Updates. When a new snapshot build is avaialable, your will also receive a notification. Devices flashed via the installer will only get updates when a new stable snapshot build is available.
• Can I update to a nightly build?
  • If you are feeling adventurous, sure. You will need to go to device page and download the zip file for your device. Save the zip to your SDCARD and you can install via Recovery. You may need to wipe cache and data after installing via recovery.
• How do I get back to stock?
  • You may perform a full backup from recovery, after flashing recovery (you will have to do this manually, at the moment) and then copy it off the device, if you don’t have an external sdcard. If you’ve already run the installer, you will have to find stock images and flash them using fastboot or Odin.

Before you start

• Back up your data!
• Back up your data. Did I say this already? Backups made in recovery are not safe unless they are made to a true external sdcard. If you want to go back to stock, make preparations for doing so before running the installer.
• Use a high-quality USB cable. A cable that works for charging won’t necessarily work reliably for data transfer. The OEM cable that came with your phone should be a good choice, but if the connector has been stressed often enough almost any cable can become unreliable.
• Don’t move your phone while installing. After you click ‘Install’, unless you need to unlock your bootloader or interact with the phone for some reason, leave it on a level surface with as little strain on the USB cable as possible until the install is complete.
• Charge your battery. Don’t attempt the install with a partially drained battery.
• Don’t use a USB hub. Plug your cable directly into a port on the workstation.
• Disable any anti-virus software for the duration of the install.

Supported Devices

Code Name	Device	Windows	Mac	Latest installer build
crespo	Google Nexus S	Yes	Yes	11.0-InstallerXNPQ08Q
crespo4g	Google Nexus S 4G	Yes	Yes	10.1-InstallerBeta3
d2att	Samsung Galaxy S III (AT&T)	Yes	Yes	11.0-InstallerXNPQ09Q
d2can	Samsung Galaxy S III (Canadian)	Yes	No	11.0-InstallerXNPQ09Q
d2spr	Samsung Galaxy S III (Sprint)	Yes	Yes	11.0-InstallerXNPQ09O
d2tmo	Samsung Galaxy S III (T-Mobile)	Yes	Yes	11.0-InstallerXNPQ09O
d2usc	Samsung Galaxy S III (US Cellular)	Yes	Yes	11.0-InstallerXNPQ09O
d2cri	Samsung Galaxy S III (Cricket)	Yes	Yes	11.0-InstallerXNPQ09O
deb	Google Nexus 7 2013 (LTE)	Yes	Yes	11.0-InstallerXNPQ25S
flo	Google Nexus 7 2013 (WiFi)	Yes	Yes	11.0-InstallerXNPQ25S
grouper	Google Nexus 7 (WiFi)	Yes	Yes	11.0-InstallerXNPQ25S
hammerhead	Google Nexus 5	No	Yes	11.0-InstallerXNPQ25S
hercules	Samsung Galaxy S II Hercules	Yes	No	10.2-InstallerWPPQ50S
i9100	Samsung Galaxy S II (Intl)	Yes	Yes	10.2-InstallerWPPQ50S
i9300	Samsung Galaxy S III (Intl)	Yes	Yes	11.0-InstallerXNPQ08Q
jfltecan	Samsung Galaxy S4 (Canada)	Yes	Yes	11.0-InstallerXNPQ09O
jfltecri	Samsung Galaxy S4 (Cricket)	Yes	Yes	11.0-InstallerXNPQ09O
jfltecsp	Samsung Galaxy S4 (C Spire)	Yes	Yes	11.0-InstallerXNPQ09O
jfltespr	Samsung Galaxy S4 (Sprint)	Yes	Yes	11.0-InstallerXNPQ09O
jfltetmo	Samsung Galaxy S4 (T-Mobile)	Yes	Yes	11.0-InstallerXNPQ09O
jflteusc	Samsung Galaxy S4 (US Cellular)	Yes	Yes	11.0-InstallerXNPQ09O
jfltexx	Samsung Galaxy S4 (Intl)	Yes	Yes	11.0-InstallerXNPQ09O
l900	Samsung Galaxy Note II (Sprint)	Yes	Yes	10.2-InstallerWPPQ50S
m7att	HTC One (AT&T)	Yes	Yes	11.0-InstallerXNPQ08Q
m7spr	HTC One (Sprint)	Yes	Yes	11.0-InstallerXNPQ08Q
m7tmo	HTC One (T-Mobile)	Yes	Yes	11.0-InstallerXNPQ08Q
m7ul	HTC One (Unlocked)	Yes	Yes	11.0-InstallerXNPQ08Q
maguro	Google Galaxy Nexus (GSM)	Yes	Yes	11.0-InstallerXNPQ25S
mako	Google Nexus 4	Yes	Yes	11.0-InstallerXNPQ25S
manta	Google Nexus 10	Yes	Yes	11.0-InstallerXNPQ25S
n7000	Samsung Galaxy Note (Intl)	Yes	Yes	10.2-InstallerWPPQ50S
n7100	Samsung Galaxy Note II (GSM)	Yes	Yes	10.2-InstallerWPPQ50S
quincyatt	Samsung Galaxy Note (AT&T)	Yes	No	10.1-InstallerBeta3
quincytmo	Samsung Galaxy Note (T-Mobile)	Yes	No	10.1-InstallerBeta3
skyrocket	Samsung Galaxy S II Skyrocket	Yes	No	10.2-InstallerWPPQ50S
t0lte	Samsung Galaxy Note II (GSM LTE)	Yes	Yes	11.0-InstallerXNPQ08Q
t0lteatt	Samsung Galaxy Note II (AT&T)	Yes	Yes	10.2-InstallerWPPQ50S
t0ltetmo	Samsung Galaxy Note II (T-Mobile)	Yes	Yes	10.2-InstallerWPPQ50S
t769	Samsung Galaxy S II (T-Mobile)	Yes	No	10.2-InstallerWPPQ50S
tilapia	Google Nexus 7 (GSM)	Yes	Yes	10.2-InstallerWPPQ50S
toro	Google Galaxy Nexus (Verizon)	Yes	Yes	11.0-InstallerXNPQ25S
toroplus	Google Galaxy Nexus (Sprint)	Yes	Yes	11.0-InstallerXNPQ25S

as of 2014-03-05

The full list of supported ro.product.device values:
crespo
crespo4g
d2att
d2can
d2cri
d2spr
d2tmo
d2usc
deb
flo
grouper
GT-I9100
GT-I9100M
GT-I9100P
GT-I9100T
GT-I9300
GT-N7000
hammerhead
hercules
i9100
i9300
jflte
jfltecan
jfltecri
jfltecsp
jfltespr
jfltetmo
jflteusc
jfltexx
jgedlte
m0
m7
m7att
m7spr
m7tmo
m7ul
m7wls
maguro
mako
manta
n7000
n7100
quincyatt
SGH-I717
SGH-I727
SGH-T769
SGH-T879
SGH-T989
t03g
t0lte
t0lteatt
t0ltecan
t0ltespr
t0ltetmo
tilapia
toro
toroplus

If your device is not on this list, you will see an ‘unsupported device’ message.

Having trouble?

General troubleshooting

Device gets stuck booting at spinning CM logo animation, won’t boot all the way

• The installer lost communication during the install, usually due to a faulty USB cable or intermittent connection. You need to power down the phone, then boot it into recovery mode – different phones have different key combinations to boot into recovery. Search for “recovery mode + your phone model”, or find the manual installation instructions for your device on this wiki. Once you’re in recovery mode, you can either:

1. Perform a factory reset / data wipe manually from the recovery menu, and then reboot the phone, which will allow you to boot successfully.
2. Plug in your phone while it’s in recovery and restart the installer from the beginning and let it run through the install process again. Consider using a new USB cable.

Device not detected

• Is your device supported? Refer to the supported devices list above.
• Have you installed and run the Android app? It will prepare your device for installation. Run the Android app and follow the instructions.
• Try unplugging your device and plugging it into a different port. Windows will sometimes fail to recognize a device until it’s unplugged and replugged.
• Your USB cable may not be up to par.

‘We couldn’t talk to your phone’

• Disable your anti-virus. No, really, disable your anti-virus. It interferes with the tools we use to write your recovery partition, among other things. Make sure to disable it for long enough that the installer can complete the full installation.
• Plugging the phone into a different USB port and clicking ‘Try Again’ is often sufficient to proceed.
• If you have a USB hub or a docking station, try the installation without it. Unplug from the hub or docking station completely.
• If you get this repeatedly at different stages of the install, you almost certainly have a bad USB cable.
• If the installer doesn’t detect your device after a reboot, and it’s stuck in download mode, it’s generally safe to hold down power or remove the battery (if the phone allows it) to power the phone off. You may attempt the installation again, it may be successful.
• Disable the USB selective suspend setting in the Control Panel. It’s found under Power Options > Advanced Settings > USB settings.

USB not connecting after running the installer

• Some users are unable to see their device connected to their PC after installing CyanogenMod. This is most likely due to drivers not picking up the connected device in Windows.
• Plug your device in to the PC and open Device Manager on your PC.
• Look for unrecognized hardware (yellow triangle) and right click on the device. ‘Select Update driver software…’
• Next select ‘Browse my computer for driver software’
• select ‘Let me pick from a list of device drivers’
• Select ‘Android Device’ from the ‘Select your device’s type from the list below’ (if Android Device doesn’t work, you can also try ADB Interface)
• Select the driver you wish to try and click Next. This will attempt to install the driver.
• Click Finish to complete and check to see if your device is recognized by your PC.
• If these attempts fail, you may want to go to the manufactures website and download any driver utilities they have for your device.

Advanced troubleshooting

‘We couldn’t talk to your phone’ – Samsung devices ONLY

• If you have Kies installed, uninstall it. Reboot, and run the installer again.
  • On a Mac, even after reboot some Samsung kernel extensions may still be loaded. Open a terminal and find them with kextstat | grep -i samsung, then unload with sudo kextunload -b com.whatever.whatever.
• Make sure the USB connection uses PTP mode, not MTP
• If your Samsung device is still unable to communicate after using the general tips above, you can try to manually install the Download Mode driver.

1. Download the zadig file needed to install additional drivers from http://zadig.akeo.ie/
2. Once you have the file, place your phone in Download Mode. This can be achieved by one of the following methods:
   • ADB command (if you use the Android SDK) – adb reboot download
   • Using hardware key buttons. Power device down and use hard key combos to boot up (they vary by Samsung model): Volume Down + Home Button (depends on model) + Power Button. At the Warning!! screen hit the Volume up arrow. If this does not work for your model or you do not have a home button, Google is your friend.
   • Using the installer. The installer usually gives the error message and leaves the device in Download Mode. Leave the device in Download Mode and proceed to follow these instructions
3. With the Samsung device in Download Mode, plug it in to the PC.
4. Run the zadig executable file you downloaded from http://zadig.akeo.ie/
5. In zadig, select Options > List All Devices
6. From the drop down, look for your device to show as ‘Gadget Serial’ or ‘MSM8x60’ and select it.
7. In the drop down next to the green arrow are 3 options: WinUSB, libusbK, and libusb-win32. Try the first option, WinUSB, and click the Replace/Reinstall Driver button.
8. Open Device Manager in Windows. Look under ‘Universal Serial Bus devices’ and see if your device is now recognized by Windows. If not, repeat the previous step trying the one of the other two driver alternatives – libusbK and libusb-win32
9. Once you have a driver installed from zadig, you can reboot the Samsung device. Try the installer again. Now that you have manually applied the driver needed by the CyanogenMod Installer, it should recognize the device and no longer present the ‘We couldn’t talk to your phone’ error message.

• The last resort is to delete any drivers from Device Manager and start fresh. So with your device in download mode, and plugged in to USB, check Device Manager. Look through the USB devices to find your device (it will show up as ‘Gadget Serial’ or ‘MSM8x60’), right click on it and select the Uninstall device driver option to remove the driver. Reboot. Either simply run the installer again, or use Zadig to install the device driver and then run the installer.

“rooting”

First, see the discussion on wikipedia for the basics.

To make things confusing, the term “root” can mean several different things in the computing world, depending on the context:

• Rooting is the process of acquiring root (or administrator) privileges on the device. (“I rooted my phone.”) This is the context described in the Wikipedia link above.

• “root” is also the actual name for the administrator user in many UNIX-based systems such as Linux. (“I logged into the root account so I could delete some system-level files that an ordinary user can’t delete.”)

• Similarly, to have root access also means having administrator-level privilages. (“I realized to delete those files, I’d need root access.”)

• The root directory is ALSO the “top” (or first) branch in a directory tree. In other words, it is / in Linux or C:/ in Windows. (“Those files I deleted were in the root directory.”)

“jailbreaking”

Jailbreaking is a term that originated in the walled-garden world of Apple that does not have a single clear analog in the Android world. Because Apple has created so many tight restrictions over what software can be run on an iDevice such as iPhone and iPod, special steps must be taken to do a variety of operations ranging from:

• enabling the iDevice’s bootloader to allow unofficial software to be loaded
• giving apps and the user escalated privileges to do operations that an app can normally not do in the standard environment (aka “rooting”)
• installing apps without the App Store’s involvement (aka “side-loading”)
• allowing extensions, theming, and other modifications to iOS’ look, feel, and behavior
• permit booting into multiple operating systems such as Linux or even Android in addition to iOS
• etc.

The activities, each of which is technically distinct, appear to have fallen under the general category of “jailbreaking”, which combine a number of different facets and goals to cover the general notion of overcoming Apple’s inherent iOS restrictions.

Although the term is sometimes used by those who do not appreciate the technical distinctions as a general “catch all”, Android and CyanogenMod users typically do not use the term “jailbreaking” due to this vagueness, preferring terms that are more descriptive, distinct, and appropriately specific such as “rooting”, “side-loading”, etc.

Android, being open source, does not inherently restrict end users’ access to their device (though vendors may choose to do so until the devices are rooted). Additionally, many “benefits” of a Jailbroken iDevice such as the ability to side-load are already commonplace and even expected of standard Android phones and tablets.

For more on “jailbreaking” in the iOS world, see this comprehensive history on Techcrunch.

“side-loading”

In the world of Apple’s iOS operating system, iPads and iPhones are generally unable to normally load apps from any source except the official App Store. Android works differently. Google’s Play Store is a source for many hundreds of thousands of apps that can be downloaded and installed automatically. However, the process of “side-loading” allows you to directly install an app from your computer or via any non-Play Store source, such as directly from a web site or even another device.

This process of loading an app that didn’t originate from a store is very common in the Android world and is simply a matter of checking a box in the Settings to enable it.

With Apple’s tighter control of the user experience, steps such as “jailbreaking” must be taken to enable side-loading. Not so for Android. Generally speaking, you can load anything you want.

(Exceptions to this include severely-restricted incarnations of Android that appear on some phones and tablets. CyanogenMod may be an option to remove this restriction.)

“flashing”

Flashing is a general-purpose term used to describe the process of loading software onto your mobile device. On a computer, the equivalent might be something like “reinstalling”, although not all flashing processes require a reformatting to occur.

There are typically two types of ways to “flash” a device:

The first uses a program called fastboot that is run on your computer when it is attached (typically via USB cable) to your device. You boot the device into “fastboot” mode, then use the program to “push” the new software over the cable to the device, where it is installed.

The second common flashing method uses the recovery mode of the device itself, without using a computer. The way it works usually is that a file containing the update to be flashed (usually ending in .zip) is downloaded directly to the device. Then the device is rebooted into recovery mode, at which point the recovery flashes the new software to the device.

That’s it!

“unlocking a phone”

AKA “Subsidy Unlock” — AKA “Sim Unlock” AKA “Network Unlock” AKA “Use a foreign SIM Card”

SIM-unlocking your phone will offer the benefit of allowing you to use your phone with other carriers.

In many markets, when you buy a phone (or mobile-enabled tablet), it can be “locked” so that it will only work with a particular carrier in a particular market. The process of “unlocking” a phone typically means that the device can be used with any compatible carrier in any market. The phone effectively becomes a “universal” or “international” device that can be used with a new regional carrier when travelling, for example.

Note that unlocking the phone may violate the terms of your agreement with your carrier, although some US carriers such as T-Mobile are known to send you “unlock codes” if you contact them before travelling. On the other hand, in some countries it is not permitted to lock the phone at all.

It is also important to understand that an unlocked phone still must meet the mobile network requirements for the new carrier– it must use a compatible system (such as GSM or CDMA) and support the frequencies of the new carrier as well.

“superCID”

CID is short for “Carrier IDentification”. It is a special number in the phone that restricts which firmware can be installed on a carrier’s variant of a device. The CID determines for example, that only an officially signed T-Mobile radio image can be installed on a T-Mobile phone. And it’s why you can’t flash a Vodafone ROM onto a Bell Desire Z, two devices which are otherwise very similar.

It may be helpful to think of the CID as a kind of “region coding” like you find on DVDs, where a North American DVD can’t be played in a European player. But if you hack your DVD player, you could switch it from a European player to a North American one. Or you might even hack it to play both DVDS.

You can do the same with phones. SuperCID is, as the name implies, a universal CID where the phone will accept any kind of firmware image.

“unlocking a bootloader”

The “bootloader” is the name of the program that first loads when you press the “on” button (or power button) on your device. Its responsibilities include initializing hardware and then starting the next few steps of the boot process by first loading and then running subsequent stages of the boot. These next stages load even further stages, until the operating system as a whole is loaded and you can start to use the device.

A “locked bootloader” typically has some kind of restriction on what it will load, based on a digital signature provided by an authority (such as the manufacturer of the device). Devices, which have locked bootloaders, are therefore limited in the operating system that they can load.

Many developers of free and open general-purpose computers look at locked bootloaders as a kind of “system bug” or design flaw, because they restrict the freedom of the owner of the device to replace the operating system with one which may be newer, better, faster, more secure, etc. For that reason, many otherwise “locked” bootloaders have been given a “bugfix” to removes this flaw and allow the user to replace the operating system with one that she or he prefers.

Some devices, such as Google Nexus devices, are sold with a bootloader that is locked by default and therefore only load vendor-provided updates. This is done for security purposes, as it is very easy to power off a phone, even with lock-screen security, and load custom recovery and operating system images that may allow an attacker to gain access to user data. Unlocking the bootloader is possible through the use of the fastboot tool, available for free via the android sdk, and causes an immediate wipe of user data, to prevent an attacker from using this same tool to gain access to user data.

S-OFF (Security OFF) Mode

Some bootloaders include a “Security ON” (AKA “S-ON”) mode, whereby certain operational restrictions are imposed on the boot. On some devices (such as the T-Mobile G2), the S-ON bootloader may put the operating system partition in a “read-only” mode. For others, S-ON may cause the device to adopt behavior similar to a fully-locked bootloader.
Switching the bootloader to S-OFF mode is therefore a prerequisite on some devices to allow the operating system to be modified or replaced.
Note that S-OFF does not imply that a device is rooted.

More Terminology & Concepts

See the Concepts and Vocabulary section of this wiki for discussions of additional terms such as “rooting”, “sideloading”, “jailbreaking”, “flashing”, “unlocking”, “unlocking a bootloader”, kinds of memory– “RAM”, “Internal storage”, etc. and common Android “partitions”/directories. There’s even a glossary.

CyanogenMod (pronounced /saɪ.’æn.oʊ.dʒɛn.mɒd/) is an enhanced open source firmware distribution for smartphones and tablet computers based on the Android mobile operating system. It offers features and options not found in the official firmware distributed by vendors of these devices.

Features supported by CyanogenMod include native theming support, FLAC audio codec support, a large Access Point Name list, an OpenVPN client, an enhanced reboot menu, support for Wi-Fi, Bluetooth, and USB tethering, CPU overclocking and other performance enhancements, soft buttons and other “tablet tweaks”, toggles in the notification pull-down (such as wi-fi, Bluetooth and GPS), app permissions management, as well as other interface enhancements. CyanogenMod does not contain spyware or bloatware. In many cases, CyanogenMod may increase performance and reliability compared with official firmware releases.

CyanogenMod is developed as free and open source software based on the official releases of Android by Google, with added original and third-party code.

Read more about CyanogenMod, including its development and version history, at its Wikipedia entry.

What’s a “firmware”, anyway?

Okay, here’s a little history:

In the past, many simple appliances and electronics– everything ranging from advanced toasters to microwaves to industrial machines ran on “embedded”, limited-purpose computer chips (micro-controllers and such) to control their operations and user interfaces. Those embedded systems would require miniature, specialized software to, say, let someone program the VCR or to receive input from a remote control to change a TV’s channel.

Traditionally, this software would be written on small-capacity memory chips, usually to be written once during manufacturing and never upgraded during the life of the product. This embedded software was known as “firmware” (halfway between software and hardware), and it still exists on many electronic products, containing the programming/logic stuff that makes much of the electronic gizmos you own work. Sometimes this firmware can be updated and new functions or bug fixes may be added. For something like a refrigerator or microwave, updating the firmware is usually a torturous process, and for most electronic things, it isn’t necessary.

In the case of Android phones and tablets, as well as iOS devices– despite the fact that they may appear simply to be a phone that can run apps, what you actually have in your hand is a full-fledged, general-purpose “computer”. So while in the past, the “firmware” was just the simple software to make a mobile phone work, the name “firmware” has stuck to describe the software you load onto your phone, much like you’d load any operating system onto a computer.

So to be clear– today, your Android devices are in fact very similar to your laptop and desktop computers. Because they are now based on so-called SoCs, or “systems on a chip”, modern Android devices are effectively tiny, low-power laptops, only with touch screens instead of keyboards. CyanogenMod, based on Android, is a full-fledged operating system, just like Windows, OS X, or Linux are on laptop computers. In fact, Android runs on a version of the Linux kernel, and you can even run a full Linux desktop on many Android devices just as you would on a regular laptop.

The term “firmware”, then, is just a legacy terminology to refer to the software you put on your handheld devices. But speaking realistically, you may as well think of it as “software, particularly an operating system and apps, that can be put on my device.”

Hope that helps.

But wait– is the right term “ROM” or “firmware” or what?

The term “ROM” has multiple definitions. Technically, ROM stands for Read-Only Memory, which means you cannot write to it; it is read-only, like a DVD or (Game) CD.

Device manufacturers traditionally referred to a cell phone’s included operating system as “ROMs” because they did not intend for you, the user, to replace it. And so, modders would use “ROM” as a shorthand for “ROM image” to describe what it was they were replacing. So today the files that you put in the system partition are also referred to as a ROM sometimes. You’ll hear people say “flashing a ROM”.

Whether you call CyanogenMod a “ROM” or a “firmware” or an “operating system” or a “distribution”, it all means in this case the same thing. The ambiguous terminology is just the result of a decade-long transition from simple, non-replaceable software on hand-held devices to full-fledged, updatable operating systems on a small, portable computer that fits in the palm of your hand.

And what about the “open-source” part? What’s that mean, and more importantly, why should I care?

Generally speaking, most programs (and even entire operating systems) are written from source code, a human-readable set of instructions that are “compiled” (or built into files that your computer (or in this case, your phone or tablet) can understand and run. In the case of operating systems such as Mac OS X and Windows, many of the instructions that become the operating system are kept hidden from the public. With Android, this code is made public and are licensed in such a way that anyone can reuse the code if they like.

One major advantage to having an open-source-based operating system is that many people can scrutinize the source code, looking for bugs ranging from security holes to inefficiencies to missing features and pass fixes and features and translations into new languages back to be incorporated into the next version. CyanogenMod tries to build a new, fresh “nightly” version every 24 hours for each of the devices it supports, which includes the most up-to-date changes to the source code, provided from all over the Internet. Of course, the nightly builds may also contain newly-introduced bugs, but hey, if you feel adventurous, you can help make CyanogenMod better by trying these experimental builds and reporting back bugs to the developers.

So what is the difference between Android and CyanogenMod?

About 1-2 times a year, the vanilla Android operating system (known as AOSP, or the Android Open Source Project) is internally developed, then released to the public, by Google. They provide the source code to anyone who wants to download it. The CyanogenMod community, comprised mostly of unpaid volunteers and enthusiasts from around the world, takes this newest Android code and “ports” it to dozens of new and older (aka “legacy”) devices. At the same time, other CyanogenMod developers start adding features, fixes, and improvements that Google didn’t include to the CyanogenMod code, which benefits all the devices. The CyanogenMod community has a whole infrastructure for people to build and test experimental versions, report bugs, and contribute back to the source code.

Sometimes features that started in CyanogenMod have appeared in newer version of “official” Android. And every time Android does a new “code dump” of their latest version, CyanogenMod benefits from Google’s changes.

In this way, CyanogenMod is one (but not the only) community distribution of what started as vanilla AOSP. The Android community is vibrant, with numerous “modders” and “themers” and “performance enhancers” taking the source code and doing incredible things to it. Generally, there is a spirit of sharing knowledge and empowering people to experiment with controlling their devices, often giving old phones new life, and hopefully having fun in the process.

What does it all mean to me?

CyanogenMod is an alternative operating system intended to replace the one pre-installed on your smart phones and tablets. If you’ve got an older device that isn’t getting updates anymore, or if your device seems unusually slow, or maybe you’re sick of spyware, adware, and other unwanted garbage on your phone that you can’t remove… Maybe your device is missing features or has been otherwise artificially limited in functionality. Perhaps you just could use a boost in performance. Or maybe you’d like to be more confident that your operating system has included some of the latest bug fixes.

If so, CyanogenMod might be for you.

Who Uses CyanogenMod?

We’ve set up a page for users to talk generally about why they use CyanogenMod and why you might too.

Go on, read the Testimonials and add your own!

Why Use CyanogenMod?

For a list of features and functionality, check out the Why Mod? page.