Get Halium source

Now that you have a target device selected and your build device ready, it’s time to get the sources for your target together. Let’s begin by initializing your source tree.

Initialize and download source tree

Make yourself a new directory to put your Halium source in:

mkdir halium && cd halium

This directory will be called BUILDDIR in the remaining part of the guide, when necessary, to avoid confusion.

If the target device has Android 12.0 or LineageOS 19 support, it’s recommended to select halium-12.0:

repo init -u https://github.com/Halium/android -b halium-12.0 --depth=1

If the target device has Android 11.0 or LineageOS 18.1 support, it’s recommended to select halium-11.0:

repo init -u https://github.com/Halium/android -b halium-11.0 --depth=1

If the target device has Android 10.0 or LineageOS 17.1 support, it’s recommended to select halium-10.0:

repo init -u https://github.com/Halium/android -b halium-10.0 --depth=1

If the target device has Android 9.0 (Pie) or LineageOS 16.0 support, it’s recommended to select halium-9.0:

repo init -u https://github.com/Halium/android -b halium-9.0 --depth=1

If the target device has Android 7.1 or LineageOS 14.1 support, it’s recommended to select halium-7.1:

repo init -u https://github.com/Halium/android -b halium-7.1 --depth=1

If your device does not have Android 7.1 or LineageOS 14.1 support but has support for Android 5.1 or CyanogenMod 12.1, select halium-5.1

repo init -u https://github.com/Halium/android -b halium-5.1 --depth=1

halium-7.1 is based on LineageOS 14.1

halium-5.1 is based on CyanogenMod 12.1

Now that you have initialized the Halium tree (a shallow copy due to –depth=1), you can sync all repositories included in it. This will probably take a while as it downloads several GBs:

repo sync -c -j 16

In case you want to get the full repo history at some point in the future because you want to patch, contribute, etc. You can execute the following commands from the repository directory

git remote -v # The leftmost word is the remote name
git fetch --unshallow [remote_name]

Adding your device-specific source

Okay, so now you have the default manifest for Halium. This will enable you to download the basic Android sources used to build Halium, but you’ll need to find device-specific files. These enable the build system to make Android for your device.

If there’s any part for you to make a mistake on, this will be the one. Finding the files isn’t hard, but it might take you a couple of tries to get repo’s local manifest created correctly.

First, you’ll want to find the repositories for your device on LineageOS’s GitHub organization. You can do this by typing your device’s codename into the search box. You’ll want the device repository, android_device_[manufacturer]_[device]. Take down this name, as you’ll need it later.

There will be a cm.dependencies or lineage.dependencies file in that repository that will tell you all of the other repositories that your device is reliant upon. Keep this file around as you will need it in a little bit.

Navigate into your Halium directory and create the file halium/devices/manifests/[manufacturer]_[device].xml.

Paste the following into the file:

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

</manifest>

We recommend cloning all of the repositories that you’ll find in the next steps to a personal source archive (aka, fork or import them on GitHub), then adding those personal forks to the manifest. This will help you save and share your work later.

The Device Repository

Next, we’ll fill the manifest with information. Start with your device repository. Create the following line between the <manifest> and </manifest> tags, replacing the information inside the square brackets with your own:

<project path="device/[manufacturer]/[device]" name="[repository name]" remote="[remote]" revision="[revision]" />

Note

The revision attribute may be omitted if the default revision for this remote is the one that you wish to use.

If you’re not sure of your remote, jump down to Remotes.

Dependencies

Now create more lines like the previous, using the cm.dependencies or lineage.dependencies file you found earlier in your device repository. This file lists all of the other repositories that you need to build for your selected device. It’s listed in a fairly straightforward way, so create a line for each of the entries in there using the following template:

<project path="[target_path]" name="[repository]" remote="[remote]" revision="[revision]" />

The target path is found in the repository’s name. The preceding “android” or “proprietary” is omitted and underscores are replaced with slashes. For example, android_device_lge_bullhead goes in device/lge/bullhead.

Vendor blobs

Vendor blobs go in the vendor/ folder in your Halium source tree. You will need to find these in a repository or otherwise and add them to your source tree. Check if your device’s vendor is listed in TheMuppets’ GitHub organization, then open the repository to see if your device’s codename is inside on your desired branch.

If you are unable to find your device in TheMuppets, you will need to find another repository with the vendor files somewhere.

Remotes

A remote entry specifies the name, location (fetch) prefix, code review server, and default revision (branch/tag) for source.

You can create a remote by adding a remote tag to your manifest.

<remote  name="aosp"
     fetch="https://android.googlesource.com"
     review="android-review.googlesource.com"
     revision="refs/tags/android-7.1.1_r25" />

Only the name, fetch, and revision attributes are required. The review attribute specifies a Gerrit Code Review server, which probably won’t be useful for initial porting purposes.

For example, let’s say that you have a bunch of repositories at https://github.com/MyUserName/ and your desired branch name is cm-14.1 in each. You would create a remote as follows and place it into your local manifest:

<remote name="mun"
    fetch="https://github.com/MyUserName"
    revision="cm-14.1" />

There are also some remotes available to you by default, though they differ between halium-5.1 and 7.1. The following tables will help you identify these. See more information on these remotes by viewing the top of .repo/manifest.xml in your initialized BUILDDIR.

halium-7.1

These remotes are available to you by default in halium-7.1:

Remote Name Remote Description, URL
aosp Android Open Source Project, https://android.googlesource.com
los LineageOS, http://github.com/LineageOS
hal Halium (link to GitHub root for legacy reasons), http://github.com
them TheMuppets, http://github.com/TheMuppets
them2 TheMuppets (for some xiaomi vendor repos) https://gitlab.com/the-muppets

If you do not specify a remote, aosp is assumed.

halium-5.1

Remote Name Remote Description, URL
phablet Canonical Ubuntu Phone compatibility, https://code-review.phablet.ubuntu.com
aosp Android Open Source Project, https://android.googlesource.com
cm CyanogenMod, https://github.com/CyanogenMod
ubp UBports (link to GitHub root for legacy reasons), https://github.com
halium Halium (link to GitHub root for legacy reasons), https://github.com
ab2ut Vendor blobs for UBports builds, https://github.com/ab2ut

If you do not specify a remote, phablet is assumed.

Sync

Now that you’ve got your manifest filled out, simply type the following to get all of your source (replace DEVICE with your device’s codename):

./halium/devices/setup DEVICE

This will first link your manifest from Halium devices to .repo/local_manifests/device.xml and then sync all repositories. This can take a while as it will download up to 2 GB of sources. If you have a fast connection, you may set an extra JOBS=[number] environment variable at the beginning of the command to make more parallel downloading jobs. We generally recommend 12, which is the default.

Document

After following these steps, create an issue on the Halium project management repository to document your porting progress. Also create a pull request containing your manifest on the Halium devices repository. You should link the manifest on Halium devices in your project management issue. Alternatively you can also use a link to the pull request, if the manifest was not merged already.

Next steps

Now that you’ve got your source tree downloaded, you can move on to the next page where we’ll start to build it!