Doc: Using local manifests

Introduction

Normally when you do a repo sync, dozens of git repositories are updated from CyanogenMod's github account. to your computer.

The regular manifest: manifest.xml

There is a master list of all the git repositories that together comprise the CyanogenMod source code. That master list, or "manifest", is located in the source code in the hidden .repo directory (relative to the source code's root folder). The .repo directory was created when you first did your repo init command before you first downloaded the source.

The file is called, appropriately enough, manifest.xml, and 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 branch of the git repository is used.

Note:

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.

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

There must be a better way. Enter the local manifest.

The local manifest

Creating a local manifest allows you to customize the list of repositories on your copy of the source code by overriding the official manifest. In this way you can add, remove, or replace source code in the official manifest with your own. By pointing to new git repositories, (which need not even reside on the github site,) you can continue to synchronize with the repo sync command just as you would before. Only now, not only are official updates pulled from the regular manifest, but the remote git repositories specified in your manifest will also be checked, and new updates pulled to your source code.

Overriding the manifest

To override the contents of manifest.xml, you will need to write (or borrow) a plaintext XML file that defines the repos you want to pull from. There are two ways you can do this. The old deprecated way is to create a local_manifest.xml in the .repo directory. The new way (available in repo versions >= 1.19) is to create a folder called local_manifests and put that inside the .repo directory, then put your XML inside that directory. You can place as many override files in .repo/local_manifests as you like and repo will pick them up during the next sync. You can call the files anything you like as long as they end in .xml.

An example

Take a look at the following local_manifest.xml file. Then we'll discuss how it works.

<?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="repo/android/hardware/ti/omap3" remote="omap" revision="jellybean"/>

   </manifest>

The first two lines containing <?xml version="1.0" encoding="UTF-8"?> and <manifest> are standard, as is the last line, which contains </manifest>.

Next, a remote for git is declared and given the name "omap". (If you're not familiar with the concept of a remote in git, it 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.

The next line removes a project (the one at http://www.github.com/cyanogenmod/android_hardware_ti_omap3) declared in the original manifest.xml. It will now no longer be synced with repo sync.

The next line defines a new project. It replaces the one that was removed (from github.com/cyanogenmod) 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 also simply add a brand-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 regular 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.

After adding .repo/local_manifest.xml, you should be able to repo sync and the source code should be updated accordingly.

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