feat(eos): build

# Building /e/OS

This guide collects the essential knowledge for building /e/OS: recognized build families, Docker commands, environment variables, and how to fetch proprietary blobs from official installable zips or devices.

## Build families overview

- **Custom builds** must rename the ROM, remove /e/OS references and OTA endpoints, and only run on /e/OS servers for permitted exceptions.

- **Unofficial builds** may tweak sources for device support but must avoid changing core features. They get no OTAs and are listed on /e/OS with warnings.

- **Community builds** offer high-quality nightly releases (hosted on GitLab or trusted mirrors) with optional OTA support and potential maintainers.

- **Official builds** require a maintainer, enjoy OTAs, and host source code on /e/OS GitLab or trusted upstreams.

## Building with Docker

1. **System requirements:** 64-bit Linux, ~400 GB free space, 16 GB RAM. Case-sensitive filesystem is mandatory (no Windows/macOS).

2. **Install Docker** per [https://docs.docker.com/install/](https://docs.docker.com/install/).

3. Pull the latest build image before each build:

   ```bash

   sudo docker pull registry.gitlab.e.foundation:5000/e/os/docker-lineage-cicd:community

   ```

4. Prepare workspace directories:

   ```bash

   sudo mkdir -p /srv/e/src /srv/e/zips /srv/e/logs /srv/e/ccache

   ```

5. **Start a build** (replace `BRANCH_NAME`, `DEVICE_LIST`, `REPO`):

   ```bash

   sudo docker run \

     -v "/srv/e/src:/srv/src" \

     -v "/srv/e/zips:/srv/zips" \

     -v "/srv/e/logs:/srv/logs" \

     -v "/srv/e/ccache:/srv/ccache" \

     -e "BRANCH_NAME=<tag>" \

     -e "DEVICE_LIST=<my-device>" \

     -e "REPO=https://gitlab.e.foundation/e/os/releases.git" \

     registry.gitlab.e.foundation:5000/e/os/docker-lineage-cicd:community

   ```

   Example `BRANCH_NAME` tags live at [https://gitlab.e.foundation/e/os/releases/-/tags](https://gitlab.e.foundation/e/os/releases/-/tags). For test builds, use `branch=v1-s` etc., and `REPO=https://gitlab.e.foundation/e/os/android.git`.

### Key environment variables

- `DEVICES` – device codenames (space-separated). **Mandatory.**  

- `BRANCH_NAME` – target Android/release tag (v1-q/v1-t). Defaults to building all available versions.  

- `INCLUDE_PROPRIETARY` – for vendors from TheMuppets (unused).  

- `MINIMAL_APPS` – set to `true` for a minimal app set.  

- `ENG_BUILD` – enables adb/root (engineering builds).  

- `OTA_URL` – specify `OTA_URL=<url>` to host your own OTA server.  

Consult the Docker image’s [Dockerfile](https://gitlab.e.foundation/e/os/docker-lineage-cicd/-/blob/master/Dockerfile.community) for the full parameter list.

## Extracting proprietary blobs

Before building, ensure you have the vendor blobs either from a running /e/OS device or from an installable zip.

1. **Block-based OTA:** extract `system.transfer.list` and `system.new.dat*`, decompress `.br` with `brotli`, then convert via `sdat2img` from [https://github.com/xpirt/sdat2img](https://github.com/xpirt/sdat2img). Mount the resulting `.img` files and run `./extract-files.sh ~/android/system_dump/`.

2. **File-based OTA:** unzip `system/*`, point `./extract-files.sh` to the extracted folder, and delete the temp directory afterwards.

3. **Payload-based OTA:** unzip `payload.bin`, run `update-payload-extractor/extract.py` (available in `/e/scripts` or via LineageOS scripts), mount `system.img` (and `vendor.img`/`product.img` if present), and run `./extract-files.sh ~/android/system_dump/`.

When blobs are ready, rerun the Docker build (they reside in `/srv/e/src/<version>/vendor/<vendor>/<device>`).

## Final notes

- Additional apps: add APKs to `android_prebuilts_prebuiltapks/` and set `CUSTOM_APPS`.  

- Minimal builds disable things like Maps, LibreOffice, etc., via `MINIMAL_APPS=true`.  

- Finished images appear in `/srv/e/zips/<my-device>`; flash via the regular `/devices` documentation.

If you need help, join the unofficial ROM builder forum or file an issue in [GitLab backlog](https://gitlab.e.foundation/e/backlog/-/issues).

- **Murena Workspace** provides synchronized mail, contacts, calendars, notes, and files based on Nextcloud (custom patches make it privacy-friendly) plus Murena Vault for end-to-end encrypted documents.

- **Murena Vault, downloadable backups, and meta search** keep your workflows inside the same trust boundary.

## Migration your data

## Migrate your data

- **Switching from a Google-backed phone:** [Migrate your data from Android & Google](migration/google/)

- **Switching from an iPhone:** [Transfer everything from iCloud](migration/apple/)

- **Backup & Restore your phone** – move files, contacts, SMS, apps, and notes to a computer before reinstalling /e/OS, and recover them afterwards with the same tools. [Follow the guide →](backup-and-restore/)

- **Update /e/OS** – use the Updater in Settings to download the latest release, install it, and reboot. [Step-by-step →](how-to-update/)

- **Factory reset without a screen** – wipe data and storage via ADB commands even if the display is unusable. [Reset guide →](factory-reset/)

- **Build /e/OS** – pull the Docker image, extract blobs, and configure the environment variables before running the build command. [Build guide →](build/)

## Learn

## /e/OS Build Types

{% include alerts/tip.html content=" To understand all about the various /e/OS Build types check out [this guide](../build-status) " %}

## Requirements for different builds:

### Custom builds

   * The source code has been modified and if the ROM is redistributed, we have several requirements:

   * Any reference to /e/OS, including “/e/OS”, and our logo must be removed from the build

   * The redistribution must not let people think that it is /e/OS.

   * **The ROM name must be changed** and possibly say that it’s been forked from /e/OS

   * Calls to our OTA server infrastructure should be removed

   * Custom ROMs can be built on /e/OS servers only for exceptional reasons (special development…).

### Unofficial /e/OS builds

   *  Source code can be modified only to reach full support on the target device.

   *  /e/OS features, list of installed apps etc. shouldn’t be modified

   *  Unofficial builds can be published on the /e/OS website at a specific place with warnings and a list of what works/what doesn’t work

   *  It doesn’t have nightly builds nor OTA updates.

### Community builds

  *  The level of quality is considered high, security updates are applied if possible,

  *  There may or may not be a ROM maintainer

  *  Community builds have nightly builds and can be updated OTA

  *  Source code have to be hosted on our GitLab instance, or on trusted sources (LineageOS GitHub group, AOSP).

### Official /e/OS builds

  * The level of quality must have reached our conditions.

  * It must have an official maintainer.

  * Official builds have nightly builds and can be updated OTA.

  * Source code have to be hosted on our GitLab instance, or on trusted sources (LineageOS GitHub group, AOSP).

Any question about this? [contact us](https://e.foundation/contact/)

## How to build the ROM?

> WARNING : This process will only work on **case-sensitive** filesystems!

> * Windows: will not work

> * macOS: doesn't work either for HPS+ filesystem - adfs not tried

> * Linux: work on Ubuntu and CentOS

> System requirement: Your computer needs to be 64-bit and running a 64-bit operating system with at least 400GB of spare hard drive space and 16GB of RAM.

### 1. Install docker

If you have not already done so, [install docker](https://docs.docker.com/install/)

### 2. Get our docker image

{% include alerts/tip.html content="Please run this step before each build, to be sure to get the last docker image."%}

```shell

$ sudo docker pull registry.gitlab.e.foundation:5000/e/os/docker-lineage-cicd:community

```

### 3. Find your DeviceCode

The device code can be found on [/e/OS devices list](../devices) or by running the following command from adb:

 `$ adb shell getprop ro.product.device`

### 4. Create directories

```shell

$ sudo mkdir -p \

/srv/e/src \

/srv/e/zips \

/srv/e/logs \

/srv/e/ccache \

```

### 5. Extract proprietary blobs

Some device vendors for example Xiaomi have blocked access to their vendor files as some of the files may be proprietary.

To get around this you will have to manually extract vendor files from your device.

{% include alerts/tip.html content="This step requires to have a device already running the latest /e/OS, based on the branch you wish to build for. If you don’t have access to such a device, refer to [Extracting proprietary blobs](extracting-proprietary-blobs) from an installable zip. " %}

Now ensure your device

- is connected to your computer via the USB cable

- has [ADB and root enabled](/pages/install-adb)

- and that you are in the `/srv/e/src/<version>/device/<vendorname>/<my-device>` folder

- now run the `./extract-files.sh` script

The blobs should be pulled into the `/srv/e/src/<version>/vendor/<vendorname>/<my-device>` folder.

Once you have fetched the vendor blobs, you can (re)run the build.

### 6. Start build

Run the following command. Don't forget to replace `<my-device>` with your device code !

```shell

$ sudo docker run \

-v "/srv/e/src:/srv/src" \

-v "/srv/e/zips:/srv/zips" \

-v "/srv/e/logs:/srv/logs" \

-v "/srv/e/ccache:/srv/ccache" \

-e "BRANCH_NAME=<tag>" \

-e "DEVICE_LIST=<my-device>" \

-e "REPO=https://gitlab.e.foundation/e/os/releases.git" \

registry.gitlab.e.foundation:5000/e/os/docker-lineage-cicd:community

```

List of tags to use for `BRANCH_NAME` is available at [https://gitlab.e.foundation/e/os/releases/-/tags](https://gitlab.e.foundation/e/os/releases/-/tags).

{% include alerts/tip.html content="We now use git tags in addition to a specific manifest for each release. It let us to know exactly what's inside each build." %}

> If you want to build a test version, you can use:

> - `BRANCH_NAME` set to v1-nougat, v1-oreo, v1-pie, v1-q, v1-r, v1-s, v1-t

> - `REPO=https://gitlab.e.foundation/e/os/android.git`

---

To understand what these parameters mean, check the document given [here](docker-command-details)

Example for Google Pixel 5

```shell

$ sudo docker run \

-v "/srv/e/src:/srv/src" \

-v "/srv/e/zips:/srv/zips" \

-v "/srv/e/logs:/srv/logs" \

-v "/srv/e/ccache:/srv/ccache" \

-e "BRANCH_NAME=v1-t" \

-e "DEVICE_LIST=redfin" \

-e "REPO=https://gitlab.e.foundation/e/os/releases.git" \

registry.gitlab.e.foundation:5000/e/os/docker-lineage-cicd:community

```

### 7. Build options

You can now customize applications installed by default in /e/OS.

* if you want to add extra applications to the default applications: add your APK to the android_prebuilts_prebuiltapks/ directory, and set the `CUSTOM_APPS` environment variable accordingly in the Docker image, before building.

* if you want to keep a minimal /e/OS build, set the `MINIMAL_APPS` environment variable to true (default is false). For now it's removing LibreOffice viewer, PDFViewer, Maps and Weather.

### 8. Get your image!

When your build is finished, please find your images inside `/srv/e/zips/<my-device>` folder. To install, please refer to our [documentation](../../devices).

## Need more help

If you need help, please check with other ROM builders who are active [on our forum](https://community.e.foundation/c/e-devices/unofficial-builds/92) and build /e/OS unofficial ROM's. Internet search for guides on android ROM building would also turn up sites which should be helpful.

To find more information about our docker image and its environment variables click [here](https://gitlab.e.foundation/e/os/docker-lineage-cicd).

To report an issue about a build, please refer to [this guide](report-an-issue)

## Objective of the document

When running the Docker command to build an /e/OS image we need to pass a few parameters. 

These environment variables can at times be confusing to the user.

Here we explain what some of the important commands mean. 

{% include alerts/tip.html content="Parameters marked with an * are mandatory " %}

## List of environment variables

**DEVICES**: the device codenames, separated by a space. This parameter is mandatory.

**BRANCH_NAME**: the android version to build (v1-q, v1-pie, v1-oreo or v1-nougat). If not set, it will build for all android version available for each device.

**INCLUDE_PROPRIETARY**: to vendors from the TheMuppets (not used since we have our own)

**MINIMAL_APPS**: Used to ship a device with Minimal Apps. Set to false by default.

**ENG_BUILD**: run an engineer build. Will enable adb by default Set to false by default

**OTA_URL** : To run an OTA server for your build. 

> Format would be `OTA_URL=ota-server-url`

## Conclusion

This list is not complete. A few parameters which are not required or relevant to the users or ROM builders are not included here

Let us know if you need more clarification on some of these or other parameters and we will add them to this document. 

To checkout the full list of available parameters have a look at [this document](https://gitlab.e.foundation/e/os/docker-lineage-cicd/-/blob/master/Dockerfile.community)

To write to us use the {% translate content.contact_helpdesk %} with your suggestions.

 No newline at end of file

## Introduction

Proprietary blobs can be extracted either from a device already running /e/OS or from an /e/OS installable zip. In this guide we will describe the steps required to extract proprietary files from installable zips.

Before beginning, it is required to know the difference between the types of OTAs:

* **Block-based OTA**: the content of the system partition is stored inside of an `.dat`/`.dat.br` file as binary data.

* **File-based OTA**: the content of the system partition is available inside a folder of the zip named `system`.

* **Payload-based OTA**: the content of the system partition is stored as an `.img` file inside of `payload.bin`.

If your zip has no `system` folder or it is nearly empty and a file named `system.transfer.list` exists at the root level, then what you have is a block-based OTA. Jump to [Extracting proprietary blobs from block-based OTAs](#extracting-proprietary-blobs-from-block-based-otas) in this case.

If you have the entire content of the system partition inside the `system` folder and no `system.transfer.list`, then what you have is a file-based OTA. See [Extracting proprietary blobs from file-based OTAs](#extracting-proprietary-blobs-from-file-based-otas).

You may also have a payload-based OTA, which is what your device will use if it uses the A/B partitioning system. If that is what you have, jump to [Extracting proprietary blobs from payload-based OTAs](#extracting-proprietary-blobs-from-payload-based-otas).

## Extracting proprietary blobs from block-based OTAs

Some block-based OTAs are split into multiple files, for the system partition and the other partitions like vendor, product, oem, odm and others.  You can verify if yours is split by looking for the corresponding `*.transfer.list` files for each in the root of the installable /e/OS zip.

If you have a split block-based OTA file then you will need to extract, decompress and convert each one in a similar manner to system and vendor as outlined below.

If you do not have a split OTA file, you may skip any step that references `vendor.transfer.list` and `vendor.new.dat.br` or `vendor.new.dat`

Create a temporary directory and move there:

```

mkdir ~/android/system_dump/

cd ~/android/system_dump/

```

Extract `system.transfer.list` and `system.new.dat.br` or `system.new.dat` from the installable //e/OS zip:

```

unzip path/to/e-*.zip system.transfer.list system.new.dat*

```

where `path/to/` is the path to the installable zip.

If your OTA includes `vendor.transfer.list` and `vendor.new.dat.br` or `vendor.new.dat` (other others), extract them from the installable /e/OS zip as well:

```

unzip path/to/e-*.zip vendor.transfer.list vendor.new.dat*

```

where `path/to/` is the path to the installable zip.

In the case of `system.new.dat.br`/`vendor.new.dat.br`/etc. (a [brotli](https://en.wikipedia.org/wiki/Brotli) archive) exists, you will first need to decompress them using the `brotli` utility:

```

sudo apt-get install brotli

brotli --decompress --output=system.new.dat system.new.dat.br

```

And if you have a `vendor.dat.new.br` (or others) file:

```

brotli --decompress --output=vendor.new.dat vendor.new.dat.br

```

You now need to get a copy of `sdat2img`. This script can convert the content of block-based OTAs into dumps that can be mounted. `sdat2img` is available at the following git repository that you can clone with:

```

git clone https://github.com/xpirt/sdat2img

```

Once you have obtained `sdat2img`, use it to extract the system image:

```

python sdat2img/sdat2img.py system.transfer.list system.new.dat system.img

```

And if you have a `vendor.dat.new` (or others) file:

```

python sdat2img/sdat2img.py vendor.transfer.list vendor.new.dat vendor.img

```

You should now have a file named `system.img` that you can mount as follows:

```

mkdir system/

sudo mount system.img system/

```

If you also have a file named `vendor.img`, you can mount it as follows:

```

sudo rm system/vendor

sudo mkdir system/vendor

sudo mount vendor.img system/vendor/

```

You must also now mount any other image files that you have in their respective directories.

After you have mounted the image(s), move to the root directory of the sources of your device and run `extract-files.sh` as follows:

```

./extract-files.sh ~/android/system_dump/

```

This will tell `extract-files.sh` to get the files from the mounted system dump rather than from a connected device.

Once you've extracted all the proprietary files, unmount the vendor dump if you mounted it earlier:

```

sudo umount ~/android/system_dump/system/vendor

```

Then unmount the system dump:

```

sudo umount ~/android/system_dump/system

```

Finally, unmount any other images before deleting the no longer needed files:

```

rm -rf ~/android/system_dump/

```

## Extracting proprietary blobs from file-based OTAs

Create a temporary directory to extract the content of the zip and move there:

```

mkdir ~/android/system_dump/

cd ~/android/system_dump/

```

Extract the `system` folder from the zip:

```

unzip path/to/e-*.zip system/*

```

where `path/to/` is the path to the installable zip.

After you have extracted the `system` folder, move to the root directory of the sources of your device and run `extract-files.sh` as follows:

```

./extract-files.sh ~/android/system_dump/

```

This will tell `extract-files.sh` to get the files from the extracted system dump rather than from a connected device.

Once you've extracted all the proprietary files, you can delete the files that were extracted from the zip:

```

rm -rf ~/android/system_dump/

```

## Extracting proprietary blobs from payload-based OTAs

Create a temporary directory to extract the content of the zip and move there:

```

mkdir ~/android/system_dump/

cd ~/android/system_dump/

```

Extract the `payload.bin` file from the /e/OS installation zip file:

```

unzip /path/to/e-*.zip payload.bin

```

where `/path/to/` is the path to the installable zip.

You will now need to use a tool called `update-payload-extractor`.

To use the tool, you will need python-protobuf, if you do not already have it:

```

sudo apt-get install python-protobuf

```

You can now extract the `.img` files from the payload:

* If you have an /e/OS build tree checked out already, you can just run the script to extract the payload:

  ```

  python /path/to/e-tree/e/scripts/update-payload-extractor/extract.py payload.bin --output_dir ./

  ```

* If you don't have a /e/OS build tree checked out, you can clone our scripts repo, and then run the script to extract the payload:

  ```

  git clone https://github.com/LineageOS/scripts

  python /path/to/scripts/update-payload-extractor/extract.py payload.bin --output_dir ./

  ```

It will take a few moments. Once it's done, we will need to mount the `system.img` file, and the `vendor.img` and `product.img` files if they exist, to obtain the complete set of proprietary blobs:

```

mkdir system/

sudo mount system.img system/

sudo mount vendor.img system/vendor/

sudo mount product.img system/product/

```

Move to the root directory of the sources of your device and run `extract-files.sh` as follows:

```

./extract-files.sh ~/android/system_dump/

```

This will tell `extract-files.sh` to extract the proprietary blobs from the mounted system dump rather than a connected device.

Once it is done, unmount the system dump and remove the now unnecessary files:

```

sudo umount -R ~/android/system_dump/system/

rm -rf ~/android/system_dump/

```

 No newline at end of file