Developer Guide

Preetam D'Souza edited this page Aug 1, 2018 · 6 revisions

Interested in building Maru OS yourself or contributing to the project? This guide will walk you through setting up a development environment, building your very own Maru OS image, and installing it on your device!

Project Structure

Maru follows a very similar project structure to AOSP. There are lots of different git repositories that are part of Maru, all of which are managed by Repo and the main manifest. Repo syncs all of these different repositories to your workspace and lets you easily work with them.


  • Simply-named repositories like mflinger or blueprints are specific to Maru and will end up under your workspace's vendor/maruos/ folder
  • Multi-word repositories fit into the AOSP workspace structure and list the project's directory path in your workspace, e.g. platform_external_lxc is placed under external/lxc in your workspace ("platform" is added just to keep it consistent with AOSP's naming)
  • Upstream AOSP forks are prefixed by android_
  • Device-specific repositories are prefixed by device_
  • Upstream projects will have the platform_external_ prefix to match how AOSP manages upstream projects


Maru maintains several branches that correspond to Android versions.

The branches that we actively develop are:

Branch Base
master AOSP 6.0
cm-14.1 LineageOS 14.1 (AOSP 7.1)
maru-0.6 LineageOS 15.1 (AOSP 8.1)

Note: Some of the kernel repositories are an exception to this--they use a similar branch name to the upstream AOSP kernel branch.

Setting up Your Environment

There are two ways to get your dev environment up and running.

Docker setup (recommended)

It is highly recommended to use Docker for Maru OS development! With Docker, you can guarantee that your build environment is set up the exact same way as the official build machines. It's also really easy to update your environment as dependencies change.

First, install Docker on your machine via the official instructions.

Then just pull down the developer image for the branch you want to build, e.g. maru-0.6:

$ docker pull pdsouza/maruos-devbox:maru-0.6

To run the image and enter the default "dev" account:

$ docker run --privileged -it pdsouza/maruos-devbox

Tip: The default "dev" user has password-less access to sudo.

One more thing: it's a good idea to use a data volume to mount a host directory that you will use as your main workspace. This will let you persist your workspace even if you end up deleting your container, as well as share the workspace between other containers.

To mount your host workspace directory $WORKSPACE into the container, use the -v flag:

$ docker run --privileged -it -v ~/path/to/$WORKSPACE:/var/maru pdsouza/maruos-devbox

This will mount the host workspace into /var/maru, but you can specify any path you like.

Traditional setup

If you'd rather not use docker, you can still set up your environment the old-school way.

Just take a look at the Dockerfile for the branch you would like to build and install these packages manually.

Tip: In-house builds of Maru OS use 64-bit Ubuntu 14.04, but most modern 64-bit Linux distributions should work. If you aren't using Ubuntu, you may need to find the corresponding packages for your distribution.

Configure USB access

Whether you are using Docker or not, you will need to configure USB access on your host to flash your builds:

$ wget -S -O - | sed "s/<username>/$USER/" | sudo tee >/dev/null /etc/udev/rules.d/51-android.rules; sudo udevadm control --reload-rules

See "Configuring USB Access" in the AOSP docs for more info.

Getting the Code

Maru OS uses Repo, just like AOSP, to manage all the project code. Repo makes it easy to work on projects with several Git repositories.

Set up Repo

Before you can install the Repo client, ensure you have a /bin folder in your PATH. The AOSP docs suggest creating this folder in your home directory:

$ mkdir ~/bin
$ PATH=~/bin:$PATH

Then download the repo client:

$ curl > ~/bin/repo
$ chmod a+x ~/bin/repo

Great, you've got Repo!

Sync the code

If you don't already have a workspace ready, create and enter a workspace directory where you'll store the project code:

$ mkdir $WORKSPACE

...and sync the code into your workspace:

$ repo init -u -b master
$ repo sync

Tip: repo sync can take a LONG time. Your first sync will download 50GB+ of sources!


Maru OS hooks into the AOSP build system for the majority of the build process.

Build the desktop image

Tip: You can just download the latest prebuilt image from here if you don't want to build the desktop image yourself. It can take up to 30 minutes for the build to finish.

The one exception to the AOSP build system is the build process for the desktop image.

$ cd vendor/maruos/blueprints
$ ./ -b debian -n jessie

Tip: You may need to run the last ./ script with sudo if you are using docker.

After half-an-hour or so, you should have the final desktop image under out/. It will look like maru-v0.x-jessie-rootfs-$SHA1.tar.gz.

Copy the final image over to vendor/maruos/prebuilts, where the AOSP build system will pick it up in the next step:

$ cp out/maru-* ../prebuilts/desktop-rootfs.tar.gz

The desktop image will be cached under vendor/maruos/prebuilts from here on out so you won't need to build it often. Just remember to generate a new image whenever maruos/blueprints has significant changes to make sure your desktop is up-to-date.

Build the device image

Get the device binaries

There are usually proprietary binary drivers ("blobs") you'll need to download to get some of your device hardware to properly function. These are not available as part of the AOSP project, so you will need to obtain them from friendly hardware manufacturers.

For Nexus devices, you can download the blobs straight from the Nexus Binaries page. Make sure to select the right binaries for your device and build version!

For example, let's say you want to build Maru OS v0.2.3 for Nexus 5 (hammerhead). v0.2.3 is based on android-5.1.1_r14 (LMY48M), so you would download the hammerhead LMY48M binaries.

Tip: To find the right binary version to select, check the manifest file that you used to sync your workspace. You can find the AOSP tag that Maru OS is based on in the manifest's default.xml. You can correlate this to the build code listed on the Nexus Binaries page here.

Uncompress each of the binary tars and run them (they are self-extracting scripts) from the root of your $WORKSPACE, making sure you read and agree to the license terms:

$ for f in *.tgz ; do tar xzf "$f" ; done
$ for f in extract-*.sh ; do ./"$f" ; done

You will now have the blobs under vendor/.

Configure the build system

You'll need to source some environment variables to initialize the build system. From the top of your $WORKSPACE:

$ . build/

List the device build configurations with:

$ lunch

Then select the device you'd like to build. Any of the devices with the prefix maru_ are supported by Maru OS. For instance, select maru_hammerhead-userdebug for a developer build for Nexus 5 (hammerhead).

Now build!

$ make -jX

...where X is the number of CPU cores on your dev machine.

Tip: This build can take a long time. Set up ccache to speed things up.

Flashing Builds

Connect your device to your machine over USB, and reboot your device into the bootloader:

$ adb reboot bootloader

...and flash your build:

$ fastboot -w flashall

Tip: You may need to unlock your bootloader if this is the first time you are flashing custom software.

Flashing with Docker

You will need to give your container USB access by bind mounting /dev/bus/usb:

$ docker run --privileged -it \
    -v /dev/bus/usb:/dev/bus/usb \
    -v ~/path/to/$WORKSPACE:/var/maru \

References / Further Reading

You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.