Doc: Using manifests
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
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 manifest file itself is updated every time you do a
repo sync. In this way, the list of all the component git repositories is kept up-to-date, along with the source.
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:
<?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> 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 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
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 syncwill 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.
You can use local repositories in the manifest by creating a remote that points to
file:///path/to/source. For example:
<remote name="local-omap" fetch="file:///home/username/myomap" />
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
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
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.