admin

Basic language info

Android is written in a combination of C, C++, and Java. Here’s a bit of a breakdown:

• the very low-level stuff like the kernel, libc (or bionic as it’s known in the android world), and many Linux-ish parts of Android are written in C.

• Slightly “higher”-up stuff, as well as external, 3rd-party open-source programs incorporated into Android may be written in C or C++. This includes everything from ART (the Android Runtime environment, which runs end-user programs), networking tools, sound processors, shell tools, graphics drivers, and that sort of thing.

• The user-facing Android “framework” stuff such as the UI elements, as well as most apps themselves, are written in Java. This is the stuff that most people think of when they think of “Android”, because it deals with much of what they see and interact with.

You can learn more about any of these languages from the external online resources.

.mk files, Makefiles, and the /build directory

There is a whole build system which is used to create a flashable .zip file from source. The various Makefile scripts used to control this process are primarily located in the /build directory.

It may be useful to know the basics of how it works– essentially, the various components/programs which together make up Android are each built independently through Android-specific Makefiles called Android.mk. The Android.mk generally exists for each sub-project (or “module”) in its source-code directory. This file directs the build system on exactly how to build that module, and where to put it in Android’s directory structure.

The files, once built, end up in the /out/target/project/CODENAME directory (replace CODENAME with the code name of the device). From there, they are zipped up and the final flashable (by recovery) .zip and flashable (by fastboot) .img files are produced.

You can actually get a peek at what’s been built there in /out, as the directories that are turned into the .img and .zip files are still around.

The various source code directories

In addition to the /build directory, the Android source code is organized into a hierarchy of folders. Take a look here at a brief description of what’s where in the source code.

The $OUT directory

kernel This is the kernel, obviously.

/system — this contains all the stuff that will become the /system folder on Android.

/root — these files contain the files that are turned into the ram disk loaded and run by the kernel. The first program to be run by the kernel is called init, and it uses the init.rc and init.CODENAME.rc files to determine what happens next. See an discussion of that here.

/recovery/root The ramdisk that contains the recovery mode is here.

Shortcut commands every CM dev should know

These commands are really useful for developing w/CM. All these commands are meant to be typed from your computer, not the shell on your device (except where indicated).

Commands

• $ . build/envsetup.sh — Note the “.” at the beginning. This will load the environment variables to your shell as well as aliases needed for the rest of these shortcuts.

• croot — this command will take you to the root of the source code.

• mm and mm -B — this is the “make module” command and it is very useful if you are working on a particular module (that is, a section of the code to be built) and don’t want to have to rebuild everything just to test it. To use it, cd into the directory that you want to test, then just type mm to build just the module in the working directory. If you want to start the build from scratch, add the -B. This is a good companion with adb sync system below, which you can use to push the newly built files directly to your device for testing without having to reflash everything.

• Note: In case of error try building the module with all the dependencies using mma . “mma .” command; and then try again with mm or mm -B

Make

• make modules — this command will show all available targets. You can build a single one by make my_target.

• make showcommands — this command will enable the verbose build mode.

ADB

• adb shell — assuming you have adb installed, this will give you a command line shell inside your device. See adb help for more.

• adb reboot — If you’ve got adb installed, this will quickly make your device reboot. Or try adb reboot recovery to reboot directly into recovery. adb reboot bootloader similarly does just what you’d expect.

• adb remount — If you’ve gotten errors trying to push files to /system due to it being in read-only mode, adb remount will remount /system into read-write mode— provided that the shell has the correct root permissions to do so. This replaces having to type a longer command by hand such as mount -o rw,remount /system (as root) or something.

• adb sync system — assuming you have adb installed, this little-known, but powerful command will sync the contents of $OUT/system with the /system directory on your device. It does require that you have write access to /system. This command is very useful for making and testing quick changes to your device. Note though that adb sync system sometimes has problems with permissions and symlinks.

The CyanogenMod Learning Center

Developer Basics

• How to enable the hidden Performance/Developer options settings in CyanogenMod
• Installing and configuring the Android SDK (Software Development Kit)
• Using adb to communicate between your device and your computer
• Using fastboot to communicate between your device and your computer
• Using logcat to troubleshoot issues and report problems
• Glossary of Common Terminology
• The CyanogenMod Issue Tracking System
• View the latest accepted changes: changelog.bbqdroid.org, cmxlog.com

Learning To Build CM

• Why Build CyanogenMod?
• Building Basics – Basic language info, .mk files, Makefiles, and the /build directory, the $OUT directory, and shortcuts every CyanogenMod developer should know.
• Setting up a Virtual Machine for CyanogenMod development
• Tracking the source code – An introduction to Git and GitHub
• Importing into Eclipse – A small how-to on importing CM source into the Eclipse IDE.
• Importing into IntelliJ – A small how-to on importing CM source into the IntelliJ/Android Studio.
• Using manifests – Add, remove, or replace source code repositories with local_manifest.xml
• Recreating CM Releases with Manifests – How to build for your device exactly like the buildbots do.
• Envsetup help – what typing . build/envsetup.sh actually does, including CyanogenMod-specific build shortcuts.
• External Android Development Resources (Master List) – The Internet Helps You Learn. Free links that teach Java, C, C++, and all things Android

Intermediate Development

• Dealing with Build Errors
• “make clean” vs. “make clobber“
• What’s where? – a peek into the source code directories
• After you build – You’ve successfully built CM. Now what?
• Adding your own app – Tutorial: How to add your own app to the build
• Submitting code for review with Gerrit: what it is, and how to use it
• Translate CM – Guide: How to translate CyanogenMod’s features to your own language
• The “edify” scripting language – how .zip files work

Advanced Topics

• An Introduction To Porting – want to port CM to a new device? Here are some tips.
• Integrated Kernel Building – some info about CM’s automatic kernel-building.
• Submitting A Port – How to get your port to a new device accepted as “official”.
• Configure SSH access on your device (OpenSSH) – How-to setup SSH on your device.
• Configure SSH access on your device (Legacy – CM7) – How-to setup SSH on your device.

Device Maintainers Only

• Some Tips – how to skip gerrit and push straight to the repo.

Introduction

When you execute repo sync, dozens of git repositories are updated from CyanogenMod on GitHub. Most of these repositories are defined in CyanogenMod’s build manifest, i.e. the default manifest. Any additional repositories that you would like synced can be added to a local manifest.

The default manifest

The master list of all the git repositories that together comprise the CyanogenMod source code are defined in CyanogenMod’s default.xml manifest. This manifest is located under the head of the android source tree in the .repo/manifests/ directory. The .repo directory was created when you first executed repo init.

The manifest is formatted in XML markup and contains information regarding which git repositories to use, where they are located on the internet, where to put them in the source code directory, and what branches of the git repositories are used. Some of these repositories are pulled, unmodified from AOSP, but most come from CyanogenMod on GitHub.

If you wanted to change this list, you could edit default.xml directly. However, this would make your local copy of the manifest conflict with the official version. This could create issues when the official manifest is updated, as it would clash with your changes. This is where local manifests come into play.

The local manifest

Creating a local manifest allows you to customize the list of repositories used in your copy of the source code by overriding or supplementing the default manifest. In this way, you can add, remove, or replace source code in the official manifest with your own. By including repositories (which need not even reside on GitHub) in a local manifest, you can continue to synchronize with the repo sync command just as you would have previously. Only now, both the official repositories from the default manifest and the additional repositories you specify will be checked for updates.

Adding and replacing repositories

To add to the contents of the default manifest, create a folder called local_manifests under the .repo directory, then create an XML file (text file with .xml extension) inside that directory. You can call the XML file anything you like, as long as it ends in .xml. The default however is roomservice.xml. Also, you can create separate XML files for different groups of repositories. e.g. mako.xml for Google Nexus 4 related repositories and cat-eater.xml for an unofficial device on which you’re working.

Let’s start with an example which we can use to describe the syntax:

<?xml version="1.0" encoding="UTF-8"?>
<manifest>

  <remote name="omap" fetch="git://git.omapzoom.org/" />

  <remove-project name="CyanogenMod/android_hardware_ti_omap3" />

  <project path="hardware/ti/omap3" name="platform/hardware/ti/omap3" remote="omap" revision="jb-dev"/>

</manifest>

The first line containing <?xml version="1.0" encoding="UTF-8"?> is a standard XML declaration, telling interpreters this is an eXtensible Markup Language file. Once this is established, the <manifest> and </manifest> tags enclose some contents which the repo command will recognize.

First, a remote for git is declared and given the name “omap”. In git, a remote essentially refers to a place and method for accessing a git repository. See here for more info.) In this case, omapzoom.org is a site that contains special up-to-date repositories for Texas Instrument’s OMAP platform. This is equivalent to the following git command:

git remote add omap git://git.omapzoom.org/

The next line removes a project (specifically, cyanogenmod/android_hardware_ti_omap3) declared in the default manifest. After running repo sync, it will no longer be available in the source tree.

The next line defines a new project. In this case, it replaces the removed project android_hardware_ti_omap3 with one from Texas Instruments, using the “omap” remote that was defined above.

When adding a new project that replaces an existing project, you should always remove that project before defining the replacement. However, not every new project need replace an existing cyanogenmod project. You can simply add a new project to the source code, such as when you want to add your own app to the build.

Note that when adding new projects, there are at least three parts defined:

• remote — the name of the remote. this can be one that was defined in either the default manifest or local_manifest.xml.

• name — the name of the git project– for github it has the format account_name/project_name.

• path — where the git repository should go in your local copy of the source code.

• revision — (optional) which branch or tag to use in the repository. If this attribute is omitted, repo sync will use the revision specified by the <default ... /> tag in the default manifest.

After creating .repo/local_manifests/your_file.xml, you should be able to repo sync and the source code will be updated accordingly.

Recreating CyanogenMod releases using manifests

CyanogenMod builds as of CM 10.0.0 include (and install locally to the device) an XML file with the exact manifest of what was used to generate them. This allows users to build an exact replica of the CM version on their device, as obtained from cyanogenmodroms.com. Note: these manifests may conflict with your local manifest, so it is recommended that you move your local manifests to a backup directory.

Obtaining the manifest

In order to build using this manifest, you must retrieve the file and place it in your .repo/manifests/ folder. The file you pull can be renamed to whatever you like; in this example it is called cm-10.0.0.xml. You can obtain the manifest in one of two ways:

1. Pull the file from your device:

cd /your/repo/path
adb pull /system/etc/build-manifest.xml .repo/manifests/cm-10.0.0.xml

OR

2. Extract /system/etc/build-manifest.xml from the ROM zip and place it into .repo/manifests, manually.

Enabling the manifest

Switch to this new manifest and enable it by typing:

repo init -m cm-10.0.0.xml
repo sync

You now can build using the exact manifest that was used to generate your device’s ROM.

After you are done building with the special manifest, you can go back to mainline with:

repo init -m default.xml
repo sync

Errors

If you receive any errors, double-check to make sure that the XML is “valid”– that is, ensure that the file contains proper XML by verifying all < and > brackets match, and that all open quotations are closed properly, etc. Other problems may include missing values, such as not defining a remote and then using it.

See also

• Stack Overflow: using a local_manifest.xml with repo
• repo Manifest Format: the official, technical documentation for repo manifests

What is the Android SDK?

The Android SDK is a software development kit provided by Google for Windows, Mac OS X, and Linux computers. The Android SDK is primarily intended to help developers create, test, and debug their Android apps. To that end, the SDK provides documentation, example code, virtual Android machines for running apps, framework code, support for development environments, debugging tools, and more.

Of special interest to end users who are interested in installing and running alternative operating systems (such as CyanogenMod) are two tools in particular:

• adb — the Android Debug Bridge, which provides a conduit between your computer and your devices, allowing you to “push” files to your computer from your device, “pull” files from your device to your computer, and even interact with your device via a command-line “shell”. adb is a very useful tool that you should expect to use frequently if you’re interested in hacking around with your device.

• fastboot — fastboot is another tool used for flashing new operating systems, wiping partitions, unlocking some devices, and more.

How do I get/install the Android SDK?

You can get full installation instructions for your platform from the official Android SDK web site. If you are not interested in doing Android application development, and only intend to use the SDK tools for adb and fastboot, then look for the section titled GET THE SDK FOR AN EXISTING IDE and download the SDK Tools package.

About the JIRA project management system

With millions of people using CyanogenMod on dozens of devices, and with so many developers working on CyanogenMod from every corner of the planet, it can get hard to keep track of all the bugs, feature ideas, and other issues that users report. To help track all the conversation relating to CyanogenMod development, a web-based issue tracking and project management system is now being used by CyanogenMod.

The name of this system is called JIRA and it can be found at https://jira.cyanogenmod.org. Using JIRA, all the reports about bugs, features, and other aspects of the project are organized and tracked in one place. Issues can be assigned to particular developers, and registered users can sign up to follow specific issues and be notified as progress is made.

Using JIRA

Sign up for an account

You will need to create an account before you can submit an issue, feature request, or improvement on JIRA. Signing up is easy.

To sign up:

1. Navigate your browser to The CyanogenMod JIRA Web site.
2. Click the Sign Up link and enter your information.

NOTE: The SignUp link does not appear on the mobile version of the website, configure your browser to request the desktop version or use a desktop browser to register.

Search for existing issues

From The Official CyanogenMod JIRA Page, click the Down Arrow on the Issues menu, click Search for issues, and enter your search terms for the bug or issue you are interested in finding. Be sure Status is set to all to see if your issue has been fixed already. If you do find an unresolved existing bug report, you can click the vote link on the right of the issue to show your support for having this bug fixed.

If you do not have a solution or further technical details to provide not already covered, there is no need to make a comment.

Create a new issue

Before you report a new issue, be sure that it has not already been reported by doing a search for the bug using keywords that relate to the issue you are having. Look over the results carefully as your bug may have already been reported, and reporting a duplicate bug is heavily frowned upon.

Once you have searched the existing issues and found nothing similar has been reported, you can create a new issue.

To create a new issue:

1. Click Create Issue under your name in top left corner.
2. Choose CyanogenMod in the Project dropdown.
3. Choose the Isssue Type.
   • An issue can be tagged as a bug report, a new feature, or an improvement suggestion.
4. Fill out one of the following Issue Types.
5. Read the instructions and agree to the terms.
6. Fill out all of the fields.
   • Summary: This field is a summary of the bug you are reporting and should include relevant and useful information.
     • A good example: “Screen does not power on consistently after waking device using galaxysmtd.”
     • A bad summary: “Screen wont turn on.”
   • Model: Choose your device from this menu
   • Affects Version(s): Choose your version from the drop down menu.
   • CM Download Source: A link to the build you installed.
     • Example: http://download.cyanogenmod.org/get/jenkins/75206/cm-11-20140708-SNAPSHOT-M8-hlte.zip
   • Radio/Baseband: This is retrieved from the bootloader screen or in the ROM (Settings->About->Baseband version).
   • Kernel version: The Kernel ID string on the device (Settings->About->Kernel version).
   • Component(s): Choose the major component affected by the bug from the drop down menu.
     • Examples: APN, Launcher, GPS
   • Description: A detailed description of the issue you are reporting.
   • Attachment: Attach a logcat file with your bug report.
7. Click Create.

Request a new feature

To request a new feature:

1. Fill out all of the fields.
   • Summary: This field is a summary of the new feature you are submitting.
   • Component(s): Choose the major component involved in the new feature.
   • Description: The full description of the new feature being submitted.
   • Attachment: Attach files associated with new feature.
2. Click Create.

Suggest an improvement

To suggest a new feature or improvement:

1. Fill out all of the fields.
   • Summary: This field is a summary of the improvement you are suggesting.
   • Component(s): Choose the major component involved in the improvement.
   • Description: The full description of the improvement being submitted.
   • Attachment: Attach files associated with this improvement.
2. Click Create.

Testing on a clean system without losing your information

Ideally all bug reports should be submitted from a cleanly wiped install of CM. Of course we want to actually use our devices and wiping before every upgrade is annoying at best. However, one can wipe their device to test and still have an otherwise functional device with all their apps and data.

These instructions assume you are using CWM recovery, though the nandroid backup should be available in other recoveries.

To back up your existing system:

1. Reboot to recovery
2. Chose backup and restore from the menu
3. Chose one of the backup options on a storage you know you have several hundred MB free

To wipe

1. Chose Wipe Data / Factory reset
2. Chose yes
3. Reinstall the latest CM version you are testing
4. Chose reboot

Duplicate the issue, capture a logcat, take screenshots, etc.

(if you cannot duplicate the issue on a fresh system it is likely an app or setting you use is causing the issue; debugging this is beyond the scope of this document)

To restore:

1. Reboot to recovery
2. Chose backup and restore
3. Chose to restore from the storage you backed up to
4. Chose the most recent backup listed
5. Chose yes

Your phone will now be in the state it was before.

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