How to

Why does CM want the kernel built together with Android?

Before CM9, we depended on having prebuilt kernels in every device repository. These were compiled separately from the framework and required the device maintainer to manually update the kernel image and modules any time a change is done. In addition, kernels were not using a consistent naming scheme, many were not managed by the CyanogenMod Gerrit, and were often compiled using compilers other than the one found in the Android toolchain. This has lead to major inconsistencies, and difficulty for others to match the maintainers build. [More info here]

How to (edit and) build an officially supported kernel?

Option A: Building the full ROM (Kernel + Android) from the full CyanogenMod source

Follow the CM Build Guides for your device.
The kernel sources will be automatically downloaded if your device is supported. The ROM will be built into a ClockworkMod Recovery flashable zip file.
Note that the full CM Android and Kernel source will be downloaded (several GB) and along with the build files you will need ~40-50GB (for CM11.0, depends on your kernel) of disk space.

Option B: Building only the Kernel from the full CyanogenMod source

Follow the CM Build Guides for your device with the change explained below.
Your device kernel will be downloaded during the launch of the breakfast or lunch command as described in the build guide. Note that the full CM Android and Kernel source will be downloaded (several GB) and along with the build files you will need ~20GB (for CM11.0, depends on your kernel) of disk space.

So follow your device build guide but instead of:

$ brunch

run (also from the CM Android source root directory (croot), not from the kernel directory):

$ mka bootimage

This will only compile the kernel source into a boot.img. You will therefore save a lot of compilation time.
The boot.img file can be then flashed with fastboot or directly from the command line.
Note that to ensure kernel – ROM compatibility, your phone should run a ROM based on the same kernel version that you’re flashing, or things may break.

$ adb root
$ adb remount
$ installboot
$ adb reboot

Note: If your device supports fastboot (Samsung doesn’t), you can test the kernel instead of flashing it:

$ adb reboot bootloader
$ fastboot boot "$OUT/boot.img"

Changing the kernel configuration

The kernel configuration file used during the build process is referenced in TARGET_KERNEL_CONFIG variable in device/vendor-name/device-name/BoardConfig.mk. It generally points to kernel/vendor-name/kernel-name/arch/arm/configs/cyanogenmod_device-name_deconfig.

To make a custom kernel configuration file, you can use the configuration build tools from the kernel dir, e.g. make menuconfig, and save the resulting hidden .config file to the location specified in TARGET_KERNEL_CONFIG. Then run make mrproper from the kernel dir and go back to the CM android source root dir (croot) before building.

Re-building

To re-build the kernel after you’ve made some changes to the source files or config file, just run mka bootimage again. The build will be much faster due to caching, and selective build of modified files. Beware the errors during the re-build process: the building system may use previously built object/modules if some objects fail to build, leading to inconsistencies. In case of doubt, run mka clean.

Note that you can’t use mm‘s command for kernel modules. These commands are made for modules that use an Android.mk file and not a standard Makefile, like system (not kernel) modules.

TO AVOID: Building only the kernel from the kernel source

As of CyanogenMod 9, we are deprecating the usage of prebuilt kernel images. The build system has been modified to ask for (and build) the kernel source. So don’t follow CM oldwiki kernel build guide.

Building an official kernel from the CyanogenMod build system will ensure your are using the proper Android toolchain. It will also bring more guarantee of compatibility between the kernel and the userspace (system calls, like ioctl, should be consistent between the kernel and userspace).

Moreover, the kernel Makefile generally doesn’t take care of creating the device-specific ramdisk, embedding the kernel image (zImage) and ramdisk into a boot.img (which structure is sometimes device specific) and pushing everything, including the loadable kernel modules, to the device. Whereas by building from the full CM source, the CM build tools will automate these steps.

TO AVOID: Building only a kernel module and importing it on a different kernel version

Kernel modules (e.g. a Wi-Fi driver) are built for a specific kernel version. Indeed, the kernel module (.ko file) embed the version of the kernel it is built for (check modinfo module-name.ko). The module will not load if its version is different than the running kernel version (check uname -a from the device terminal prompt). One reason behind this version interdependency is that internal interfaces within the kernel (the interfaces used in your module to access other kernel resources/modules) can and do change between versions. [source: LKMPG]

Therefore you should build and flash a full kernel if you need to change a module.

Otherwise, and if you make no kernel configuration change, you can build a kernel module from the same exact kernel source version (i.e. Github commit) that you’re planning to import the module into. If you’ve not built the kernel yourself, this becomes highly complicated and deprecated: you may need to rebase your CM repository to the exact Github commit that your kernel was built from, extract and use the .config from your device, and eventually trick the source files that take care of defining the magic version of the built kernel module.

How to reference a custom kernel for building?

This chapter is intended for people that want to use a totally different kernel than the officially supported ones.
If you only need to modify an officially supported firmware, go back to the previous chapter and play with the kernel files in kernel/vendor-name/kernel-name (the official kernel files for your device will be downloaded after running the breakfast or lunch commands as described in the Build Guides).

Step 0. Preparing the build environment

Depending on whether your device is supported or not, follow the Build Guides or Porting Guide to prepare the Build Environment and get CM Android source code, prebuilt apps, device-specific code and proprietary blobs.

Step 1. Deploying the kernel source at the proper location

The minimal requirement is that the kernel’s source tree for that device be present at kernel/vendor-name/device-name of the CM Android source.

• Officially supported devices:
  • For devices which are part of mainline CyanogenMod and have their kernels in CM’s github, this can be accomplished by usage of CyanogenMod’s roomservice feature. Create a device/vendor-name/device-name/cm.dependencies file (if it doesn’t exist yet), with the following syntax. This will take care of downloading the source automatically into the right location.

[
 {
   "repository": "name-of-repository-in-the-CyanogenMod-github",
   "target_path": "kernel/vendor-name/device-name",
   "branch": "name-of-branch"
 }
]

• Work-in-progress, unofficial, or otherwise non-integrated devices:
  • For devices which don’t have their kernel source at the CM github, usage of local_manifest.xml is recommended in order to deploy the source at the right location, and keeping it synchronized.

• Devices using shared kernel repositories:
  • If your device shares a kernel with others, the default kernel/vendor-name/device-name path will lead to unnecessary duplication of source trees, so usage of the TARGET_KERNEL_SOURCE configuration variable in device/vendor-name/device-name/BoardConfig.mk is advised. All devices sharing that source should have the following line in their BoardConfig.mk files:

TARGET_KERNEL_SOURCE := kernel/vendor-name/unique-shared-source-name

Step 2. Configuring the device to build the kernel

After the source is in place, configuration of the device to build the kernel is trivial. Just add the TARGET_KERNEL_CONFIG variable to your device/vendor-name/device-name/BoardConfig.mk file, pointing to the configuration file name for your device (as present in kernel/vendor-name/kernel-name/arch/arm/configs). For example:

TARGET_KERNEL_CONFIG := cyanogenmod_device-name_defconfig

This will trigger the full kernel build, including the modules (if present) as specified in that configuration. Any modules built will be deployed at /system/lib/modules/ in the final image

If your device requires uImage, also ensure the following is present in your ‘BoardConfig.mk’

BOARD_USES_UBOOT := true

Step 3. Configuring the build of out-of-tree kernel modules

If your device needs modules that aren’t part of the kernel source tree, those can also be built automatically. Some hardware (Texas Instruments’ TIWLAN adapters, Broadcom’s BCM adapters) is directly supported by CM repositories, but if that isn’t your case we suggest you add your module’s source to either your device repository, or an isolated path in your kernel source.

To build these modules, the TARGET_KERNEL_MODULES variable can be used, pointing to a make target that will build and install such modules. Definition of such a target is the device author’s responsibility, the only restriction is that it is a normal makefile recipe. To include, for example, the TI WLAN modules, this can be used:

TIWLAN_MODULES:
       make -C hardware/ti/wlan/wl1283/platforms/os/linux/ KERNEL_DIR=$(KERNEL_OUT) ARCH="arm" CROSS_COMPILE="arm-eabi-" TNETW=1273 RANDOM_MAC=n REPORT_LOG=n
       mv hardware/ti/wlan/wl1283/platforms/os/linux/tiwlan_drv.ko $(KERNEL_MODULES_OUT)
       make -C hardware/ti/wlan/wl1283_softAP/platforms/os/linux/ KERNEL_DIR=$(KERNEL_OUT) ARCH="arm" CROSS_COMPILE="arm-eabi-" TNETW=1273 REPORT_LOG=n
       mv hardware/ti/wlan/wl1283_softAP/platforms/os/linux/tiap_drv.ko $(KERNEL_MODULES_OUT)
    
TARGET_KERNEL_MODULES := TIWLAN_MODULES

As a rule of thumb, you can just paste your current standalone build commands into a make recipe, replacing the kernel source path with the $(KERNEL_OUT) variable.

Step 4. Configuring the fallback to prebuilts

If for some reason the kernel source can’t be present, you can still fall back to prebuilt binaries, by defining the TARGET_PREBUILT_KERNEL variable, like this:

TARGET_PREBUILT_KERNEL := device/vendor-name/device-name/kernel

Step 5. Building the kernel or full ROM

Now that your custom kernel is linked to your device, you can build the device kernel or the device full ROM as you would do with an official kernel, as described in the first part of this page.

Full configuration example

The following is the p920’s configuration (device/vendor-name/device-name/BoardConfig.mk), which attempts to build the kernel, uses external modules, and has a prebuilt fallback:

# Try to build the kernel
TARGET_KERNEL_CONFIG := cyanogenmod_cosmo_defconfig
# Keep this as a fallback
TARGET_PREBUILT_KERNEL := device/lge/p920/kernel

KERNEL_EXTERNAL_MODULES:
make -C hardware/ti/wlan/wl1283/platforms/os/linux/ KERNEL_DIR=$(KERNEL_OUT) ARCH="arm" CROSS_COMPILE="arm-eabi-" TNETW=1273 RANDOM_MAC=n REPORT_LOG=n
mv hardware/ti/wlan/wl1283/platforms/os/linux/tiwlan_drv.ko $(KERNEL_MODULES_OUT)
make -C hardware/ti/wlan/wl1283_softAP/platforms/os/linux/ KERNEL_DIR=$(KERNEL_OUT) ARCH="arm" CROSS_COMPILE="arm-eabi-" TNETW=1273 REPORT_LOG=n
mv hardware/ti/wlan/wl1283_softAP/platforms/os/linux/tiap_drv.ko $(KERNEL_MODULES_OUT)

TARGET_KERNEL_MODULES := KERNEL_EXTERNAL_MODULES

See also

• Doc: the cm source

make is pretty smart, and picks up what has changed from the last build, so if you run repo sync and then build without cleaning, in most cases it should work just fine.

One exception would be after adding or updating proprietary vendor binaries. Per Google’s Android documentation, Building for devices, Google does recommend:

Cleaning up when adding proprietary binaries

In order to make sure that the newly installed binaries are properly taken into account after being extracted, the existing output of any previous build needs to be deleted with make clobber.

make clean does the same thing as make clobber, which is removing all generated files including those in ($OUT_DIR) if defined.

Intro: Adding a new app to the build

So after completing a build, people have been asking how to add their own app(s) to the CyanogenMod .zip file.

The “easy” way– Add it to the zip manually

One way to do this is to simply add the .apk into the .zip and then edit the recovery installation script (written in a simple scripting language called “edify“) to copy the file from the .zip to the device.

The “right” way: Make a part of the build repository so it auto-builds

Add app source to /packages/apps

You can do this manually, or you can do it via the .repo/local_manifests/*.xml. If you do it this way, a repo sync will update the source to your app from whatever git repository you name in the local manifest. It’s pretty easy to use, and allows you to override/replace/add/remove any official CM repository with one or more of your own.

Determine the name of the project from Android.mk

Regardless of how you put the source in packages/apps/, assuming that the source for the app has an Android.mk Makefile, you can get it to automatically build and install the resulting file in your $OUT directory (and thus your .zip) by simply determining the name of the project, which is typically defined in Android.mk with this:

LOCAL_PACKAGE_NAME := MyPackageName

Add the project to device.mk (or whatever .mk) in the device folder

Then just add that project to be built in the /device/[MANUFACTURER]/[CODENAME]/device.mk file.

Example:

Let’s look at the grouper device aka the Nexus 7. You want to find where the list of packages to build is for this device, in device/asus/grouper/device-common.mk.

Now you have a choice. If PRODUCT_PACKAGES was previously defined, you can add a value like this:

PRODUCT_PACKAGES += MyPackageName

The += part means to append it to the list.

Or, if it’s simpler, you can just add it to the end an existing PRODUCT_PACKAGES list of projects by appending a “\” to the last item and then adding MyPackageName at the end. Notice that you can’t put any commented lines (ie, lines starting with #) or even blank lines in the list of items to be built.

So if the list looks like this…

PRODUCT_PACKAGES := \
lights.grouper \
audio.primary.grouper

…you’d add it to the end:

PRODUCT_PACKAGES := \
lights.grouper \
audio.primary.grouper \
MyPackage

If the source for your app does not have the Android.mk makefile stuff, you’ll need to add it. You can use any of the existing packages in packages/apps as a model for what needs to be done to build your particular app.

See here for official documentation on Android .mk files.

During a build, it’s normal to see the occasional warning pop by… let it go all the way to the end and see if you get a cm-[whatever].zip file

But if it stops generally you get a message at the end that says something about an error, and then if you scroll up (or do a reverse-search for “error” from the end), you’ll get the actual line that causes the error.

I usually run into one of four types of errors, although there are more:

1. A missing file error — when the build first starts, the build system takes a look at all Android.mk files (and all the .mk files that those include, such as cm.mk or BoardConfig.mk). These Makefiles contain info about each of the projects (“modules”) that are going to be built. Some of these files, such as device/asus/grouper/device.mk, specify that as part of the build, certain non-compiled or pre-compiled files such as .gifs or binary blobs should be directly copied to a directory in $OUT (the target directory where the build goes). If the build system can’t find the file, you’ll get an error, usually really early because this stuff usually happens before other stuff is compiled. The solution is to find the missing file and supply it.
2. An error in the build system itself (as opposed to the code once the compiling starts)– sometimes (very rarely) there are syntax errors in the .mk file itself… usually this type of error will occur very very early in the build, and you can get a clue of what’s wrong from the error. If it’s not a typo, it could be a missing build tool on your system, but the errors are usually pretty helpful in indicating the issue. If you don’t know what’s up, someone in the forum or on IRC can generally help. Also, if you type git log from within the directory, you can see a list of all the changes that have been made recently to the repository. If you say git show [LONGSTRINGIDOFTHECOMMIT], it will show you what changed recently. This can help figure what the deal is.
3. a code-related error that happens during the build. This is the bulk of errors. Programming errors and such that happen as the build is going. Syntax errors and that kind of thing. The problem might be in a Java (.java) file, or in a C (.c) file, or in a C++ (.cpp) file or a header (.h) or whatever. This is just a regular building bug that needs to be fixed in the code, and may require some programming knowledge, although simple typos and such can be figured out just by looking at surrounding code. The error usually says something like “error 1” and then you have to scroll back (do a reverse-search if you can) for the word “error”, which should then show you the exact file and line # containing the error as well as a description of what the error is. This is your basic programming issue and not an Android specific thing.
4. linking error— sometimes the files themselves compile fine, but there’s a linking error when various constituent files are combined together to create one binary (which may be an executable or a library or whatever). Sometimes this is the hardest one to solve, but again, people in the forums can usually help. Errors like this usually appear at the end when something depends on something you’ve built previously, but it doesn’t work right. And again, this is nothing specific to Android. It’s a basic programming thing.

99% of the time you do a repo sync and build a fresh version, the system will be stable and there shouldn’t be any show-stopping errors that halt the build– code usually isn’t checked into upstream unless it’s been thoroughly tested. That said, sometimes bugs sneak in, especially in the days following a Google code drop. So if you find a bug and are able to fix it, be sure to submit the fix back to review.cyanogenmod.org so that it can be quickly incorporated into the build.

Source: http://forum.xda-developers.com/showpost.php?p=30711199&postcount=39

Aside from the information on this wiki, there are plenty of sites on the Internet that will teach you the basics of programming and development. Here are some of our favorite free external sites.

Programming Basics

If you’re entirely new to the world of programming, it may not be a bad idea to spend a few days perusing some of the most basic concepts before you jump into specific languages. Here are a few sites that offer some elementary lessons that will get you started.

• Code Academy — A web site dedicated to teaching you how to write programs. It’s interactive and tracks your progress, even allowing you to share what you’re learning with others. Code Academy uses the JavaScript language. JavaScript isn’t the same as Java (the language in which most Android apps are written), but the concepts are pretty much the same, and you’ll be able to apply what you learn to writing Android apps. It’s also worth noting that JavaScript is a language run on most Web browsers, so the skills you learn from this site will be instantly useful if you want to create interactive web pages and even user interface stuff in other languages.

• Khan Academy’s Programming Basics — A few videos that introduce you to what a program is. In each of the “programming basics”, just press the green “play” button for more information on the concept.

• MIT’s Introduction to Programming Class — if you’re more into traditional classroom style education, consider taking the free Open CourseWare classes from MIT. This class is for those who have little to no previous programming experience and uses the Python language. Python, a very powerful language, is available on Android devices, but concepts learned with Python also translate to Java, C, and C++.

Learn the Java language

Many apps on Android are written in Java, and much of Android’s internal frameworks are also written in Java. So having an familiarity of the Java language is helpful not only for writing your own apps, but if you want to tweak or add features to the Android user interface itself.

• Thinking in Java — a free online book by Bruce Eckel. This book teaches the language of Java. It doesn’t include stuff particular to Android, but covers the basic syntax and linguistic concepts that Java programmers use. If you’re just starting with Java, this is a good book to read. Sample code is included. Should you prefer a newer paper-version, “Thinking in Java” is available as a printed edition as well.

Learn the C language

Much of the “lower level” portion of Android are written in the C language. The Linux-based Android kernel is also written in C, and C is used by many apps as well.

Learn the C++ language

C++ is an “object oriented” version of C.

Learn about the build system (GNU Make)

• Google’s original documentation about the build system
• GNU Make manual — the Android build system is built on top of the “make” command. It’s not quite a programming language, but it is a potentially complex mix of “recipes” and “rules” that you must understand to know how Android efficiently builds all the code into a flashable .zip you can install onto a device.
• The Android-Building Group — this is Google’s official Google Group for building AOSP (Android Open Source Project– or vanilla Android from Google). If you have questions, this is a good place to find answers.

Learn about the Android kernel (based on the Linux kernel)

• How To Build A Kernel A tutorial from Google on how to build the Android kernel from scratch. CyanogenMod will automatically build the kernel as part of the build, provided that the kernel is in /kernel/vendorname/device/codename and referenced from the appropriate .mk file.

Learn about the Android Frameworks

The official Android Developer Site — This is the central documentation site from Google about development for Android– in other words, bookmark this site, as you will refer to it again and again as you create your own apps (or change the framework itself to affect apps that run).

Android classes — If you’re going to write a Java program for Android, this is the central location for learning about all the Android-specific classes available.

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.