Skip to content

Commit

Permalink
'Building' section moved to the wiki
Browse files Browse the repository at this point in the history
  • Loading branch information
@petefoth
petefoth authored Jan 13, 2025
1 parent 5ca2859 commit 91a6c2e
Showing 1 changed file with 0 additions and 228 deletions.
228 changes: 0 additions & 228 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,234 +5,6 @@ Docker microservice for LineageOS Continuous Integration and Continuous Deployme
See [the wiki](https://github.com/lineageos4microg/docker-lineage-cicd/wiki) for updated documentation


## How can I build LineageOS?

Before you start, make sure you have the latest version of our Docker image:
```
docker pull lineageos4microg/docker-lineage-cicd
```

The requirements for building LineageOS for MicroG are roughly the same as for [building LineageOS](https://wiki.lineageos.org/devices/sunfish/build):
- A relatively recent x86_64 computer:
- Linux, macOS, or Windows - these instructions are only tested using Ubuntu 20.04 LTS, so we recommend going with that.
- A reasonable amount of RAM (16 GB to build up to lineage-17.1, 32 GB or more for lineage-18.1 and up). The less RAM you have, the longer the build will take. Enabling ZRAM can be helpful. If builds fail because of lack of memory, you can sometimes get over the problem by increasing the amount of swap, but this will be at the expense of slower build times.
- A reasonable amount of Storage (~300 GB for lineage-18.1 and up). You might require more free space for enabling ccache, building for multiple devices, or if you choose to mirror the LineageOS sources (see below). Using SSDs results in considerably faster build times than traditional hard drives.

- A decent internet connection and reliable electricity. :)
- Some familiarity with basic Android operation and terminology. It may be useful to know some basic command line concepts such as cd, which stands for “change directory”, the concept of directory hierarchies, and that in Linux they are separated by /, etc.

This Docker image contains a great number of settings, to allow you to fully
customize your LineageOS build. Here you can find all of them, with the default
values between the brackets.

TL;DR - go to the [Examples](#examples)

### Fundamental settings

The two fundamental settings are:

* `BRANCH_NAME (lineage-16.0)`: LineageOS branch, see the branch list
[here][los-branches] (multiple comma-separated branches can be specified)
* `DEVICE_LIST`: comma-separated list of devices to build

Running a build with only these two set will create a ZIP file almost identical
to the LineageOS official builds, just signed with the test keys.

When multiple branches are selected, use `DEVICE_LIST_<BRANCH_NAME>` to specify
the list of devices for each specific branch (see [the examples](#examples)).

#### GMS / microG

To include microG (or possibly the actual Google Mobile Services) in your build,
LineageOS expects certain Makefiles in `vendor/partner_gms` and variable
`WITH_GMS` set to `true`.

[This][android_vendor_partner_gms] repo contains the common packages included for
official lineageos4microg builds. To include it in your build, create an XML
(the name is irrelevant, as long as it ends with `.xml`) in the
`/home/user/manifests` folder with this content:

```xml
<?xml version="1.0" encoding="UTF-8"?>
<manifest>
<project path="vendor/partner_gms" name="lineageos4microg/android_vendor_partner_gms" remote="github" revision="master" />
</manifest>
```

#### Additional custom apps

If you wish to add other apps to your ROM, you can include a repository with
source code or prebuilt APKs. For prebuilt apks, see the [android_vendor_partner_gms][android_vendor_partner_gms]
repository for examples on how the `Android.mk` file should look like.

Include the repo with another manifest file like this:

```xml
<?xml version="1.0" encoding="UTF-8"?>
<manifest>
<project name="your-github-user/your-repo" path="prebuilts/my-custom-apps" remote="github" revision="master" />
</manifest>
```

And when starting the build, set the `CUSTOM_PACKAGES` variable to a list of app names
(defined by `LOCAL_MODULE` in `Android.mk`) separated by spaces.

#### Signature spoofing

For LineageOS versions 18.1, 19.1, 20.0 and 21.0, built-in support for
signature spoofing has been added. This specifically only allows microG to
spoof its signature; no other apps are allowed to do so. If this is fine, the
`SIGNATURE_SPOOFING` environment variable may be left unset (defaulting to
`no`).

If not, two custom [signature spoofing patches][signature-spoofing] are
provided:
* "Original" [patches][signature-spoofing-patches]
* Restricted patches

With the "original" patch the FAKE_SIGNATURE permission can be granted to any
user app: while it may seem handy, this is considered dangerous by a great
number of people, as the user could accidentally give this permission to rogue
apps.

A more strict option is the restricted patch, where the FAKE_SIGNATURE
permission can be obtained only by privileged system apps, embedded in the ROM
during the build process.

The custom signature spoofing patch can be optionally included with:

* `SIGNATURE_SPOOFING (no)`: `yes` to use the original patch, `restricted` for
the restricted one, `no` for none of them and to default to built-in
signature spoofing.

If in doubt, use `restricted`: note that packages that requires the
FAKE_SIGNATURE permission must be included in the build as system apps
(e.g. as part of GMS or `CUSTOM_PACKAGES`)

These patches are currently disabled for LineageOS 21 entirely. If you have an
use case which requires the use of custom patches on 21,
[please open an issue][issue-tracker].

#### Proprietary files

Some proprietary files are needed to create a LineageOS build, but they're not
included in the LineageOS repo for legal reasons. You can obtain these blobs in
three ways:

* by [pulling them from a running LineageOS][blobs-pull]
* by [extracting them from a LineageOS ZIP][blobs-extract]
* by downloading them from TheMuppets [GitHub][blobs-themuppets] and
[GitLab][blobs-the-muppets] repositories (unofficial)

The third way is the easiest one and is enabled by default; if you're OK with
that just move on, otherwise set `INCLUDE_PROPRIETARY (true)` to `false` and
manually provide the blobs (not explained in this guide).

#### Over the Air updates

To enable OTA for you builds, you need to run a server that speaks the protocol
understood by the [LineageOS updater app][updater] and provide the URL to this
server as `OTA_URL` variable for the build.

One implementation is [LineageOTA][lineageota], which is also available as Docker
image. Follow these steps to prepare your builds for OTA:

* Run the Docker image `julianxhokaxhiu/lineageota`
* Port 80 exposed to the internet (might want to add an HTTPS reverse proxy)
* The `/srv/zips` directory/volume of the CICD image mounted at
`/var/www/html/builds/full` (can be read-only)
* Set environment variables when building
* `ZIP_SUBDIR` to `false`
* `OTA_URL` to the address of the OTA server, with `/api` appended

If you don't setup a OTA server you won't be able to update the device from the
updater app (but you can still update it manually with the recovery of course).

#### Signing

By default, builds are signed with the Android test keys. If you want to sign
your builds with your own keys (**highly recommended**):

* `SIGN_BUILDS (false)`: set to `true` to sign the builds with the keys
contained in `/srv/keys`; if no keys are present, a new set will be generated

#### Settings to control 'switchable' build steps

Some of the the steps in the build process (e.g `repo sync`, `mka`) can take a long time to complete. When working on a build, it may be desirable to skip some of the steps. The following environment variables (and their default values) control whether or not each step is performed
```
# variables to control whether or not tasks are implemented
ENV INIT_MIRROR true
ENV SYNC_MIRROR true
ENV RESET_VENDOR_UNDO_PATCHES true
ENV CALL_REPO_INIT true
ENV CALL_REPO_SYNC true
ENV CALL_GIT_LFS_PULL false
ENV APPLY_PATCHES true
ENV PREPARE_BUILD_ENVIRONMENT true
ENV CALL_BREAKFAST true
ENV CALL_MKA true
ENV ZIP_UP_IMAGES false
ENV MAKE_IMG_ZIP_FILE false
```

To `switch` an operation, change the default value of the the variable in a `-e clause` in the `docker run` command e.g.
` -e "CALL_REPO-SYNC=false" \`

The `ZIP_UP_IMAGES` and `MAKE_IMG_ZIP_FILE` variables control how the `.img` files created by the buid are handled:
- by default, the `img` files are copied - unzipped - to the `zips` directory
- if `ZIP_UP_IMAGES` is set `true`, the images are zipped and the resulting `...images.zip` is copied to the `zips` directory
- if `MAKE_IMG_ZIP_FILE` is set `true`, a flashsable `...-img.zip` file is created, which can be installed using `fastboot flash` or `fastboot update`


#### Other settings

Other useful settings are:

* `CCACHE_SIZE (50G)`: change this if you want to give more (or less) space to
ccache
* `RELEASE_TYPE (UNOFFICIAL)`: change the release type of your builds
* `BUILD_TYPE (userdebug)`: type of your builds, see [Android docs](https://source.android.com/docs/setup/build/building#choose-a-target)
* `BUILD_OVERLAY (false)`: normally each build is done on the source tree, then
the tree is cleaned with `mka clean`. If you want to be sure that each build
is isolated from the others, set `BUILD_OVERLAY` to `true` (longer build
time). Requires `--cap-add=SYS_ADMIN`.
* `LOCAL_MIRROR (false)`: change this to `true` if you want to create a local
mirror of the LineageOS source (> 200 GB)
* `CRONTAB_TIME (now)`: instead of building immediately and exit, build at the
specified time (uses standard cron format)
* `ZIP_SUBDIR (true)`: Move the resulting zips to $ZIP_DIR/$codename instead of $ZIP_DIR/
* `PARALLEL_JOBS`: Limit the number of parallel jobs to run (`-j` for `repo sync` and `mka`).
By default, the build system should match the number of parallel jobs to the number of cpu
cores on your machine. Reducing this number can help keeping it responsive for other tasks.
* `RETRY_FETCHES`: Set the number of retries for the fetch during `repo sync`. By default, this value is unset (default `repo sync` retry behavior).
Positive values greater than 0 are allowed.

The full list of settings, including the less interesting ones not mentioned in
this guide, can be found in the [Dockerfile][dockerfile].

## Volumes

You also have to provide Docker some volumes, where it'll store the source, the
resulting builds, the cache and so on. The volumes are:

* `/srv/src`, for the LineageOS sources
* `/srv/zips`, for the output builds
* `/srv/logs`, for the output logs
* `/srv/ccache`, for the ccache
* `/srv/local_manifests`, for custom manifests (optional)
* `/srv/userscripts`, for the user scripts (optional)

When `SIGN_BUILDS` is `true`

* `/srv/keys`, for the signing keys

When `BUILD_OVERLAY` is `true`

* `/srv/tmp`, for temporary files

When `LOCAL_MIRROR` is `true`:

* `/srv/mirror`, for the LineageOS mirror

## Examples

Expand Down

0 comments on commit 91a6c2e

Please sign in to comment.