Doc: Using local manifests

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.

Template:Note

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. 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: </translate>

<?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>

<translate> 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:

</translate> git remote add omap git://git.omapzoom.org/ <translate>

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.

Template:Note

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 download.cyanogenmod.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.

Referensi

http://wiki.cyanogenmod.org/w/Doc:_Using_local_manifests