Developer Guide
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!
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.
There are two ways to get your dev environment up and running.
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.
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 Debian 9 Stretch, but most modern 64-bit Linux distributions should work. If you aren't using Debian, you may need to find the corresponding packages for your distribution.
Whether you are using Docker or not, you will need to configure USB access on your host to flash your builds:
$ wget -S -O - http://source.android.com/source/51-android.rules | 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.
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.
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 https://storage.googleapis.com/git-repo-downloads/repo > ~/bin/repo
$ chmod a+x ~/bin/repo
Great, you've got Repo!
If you don't already have a workspace ready, create and enter a workspace directory where you'll store the project code:
$ mkdir $WORKSPACE
$ cd $WORKSPACE
...and sync the code into your workspace:
$ repo init -u https://github.com/maruos/manifest -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.
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
$ ./build.sh -b debian -n jessie
Tip: You may need to run the last ./build.sh 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.
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/.
You'll need to source some environment variables to initialize the build system. From the top of your $WORKSPACE:
$ . build/envsetup.sh
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).
$ 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.
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.
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 \
pdsouza/maruos-devbox