From 6412f03a94de0607247672dcd8da3e23b2a795b9 Mon Sep 17 00:00:00 2001 From: DRC Lab <85211068+DRCRecoveryData@users.noreply.github.com> Date: Sat, 20 Jun 2026 06:09:48 +1000 Subject: [PATCH] docs: add finalized crDroid build guide Co-Authored-By: Oz --- crDroid_Build_Guide.md | 228 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 228 insertions(+) create mode 100644 crDroid_Build_Guide.md diff --git a/crDroid_Build_Guide.md b/crDroid_Build_Guide.md new file mode 100644 index 0000000..fcd852c --- /dev/null +++ b/crDroid_Build_Guide.md @@ -0,0 +1,228 @@ +# crDroid Build Guide (Android 16 / branch `16.0`) +## 1) Overview +This document provides an end-to-end reference for building crDroid from source: +- Environment setup +- Source initialization +- Local manifest template for generic devices +- Build execution +- Build verification +- Troubleshooting +- Clean build procedures + +All command examples in this guide assume a Linux shell (bash/zsh) inside a Linux build environment. + +## 2) Prerequisites +### Recommended hardware +- CPU: 8+ cores +- RAM: 16 GB minimum (32 GB recommended) +- Storage: 250+ GB free (SSD recommended) + +### OS +- Linux environment required for Android ROM builds (native Linux, VM, or WSL2 Ubuntu). + +## 3) Environment Setup +Install build dependencies: + +```bash +sudo apt update +sudo apt install -y bc bison build-essential ccache curl flex g++-multilib gcc-multilib git git-lfs gnupg gperf imagemagick lib32ncurses-dev lib32readline-dev lib32z1-dev liblz4-tool libncurses6 libncurses-dev libsdl1.2-dev libssl-dev libwxgtk3.2-dev libxml2 libxml2-utils lzop pngcrush rsync schedtool squashfs-tools xsltproc zip zlib1g-dev +``` + +Install `repo`: + +```bash +mkdir -p ~/bin +echo 'export PATH=~/bin:$PATH' >> ~/.bashrc +source ~/.bashrc +curl https://storage.googleapis.com/git-repo-downloads/repo > ~/bin/repo +chmod a+x ~/bin/repo +``` + +## 4) Initialize crDroid Source +```bash +mkdir -p ~/crDroid +cd ~/crDroid +repo init -u https://github.com/crdroidandroid/android.git -b 16.0 --git-lfs --no-clone-bundle +``` + +## 5) Local Manifests (Generic Device Template) +If your target device repos are not fully covered in the main manifest: + +```bash +mkdir -p ~/crDroid/.repo/local_manifests +``` + +Create `.repo/local_manifests/.xml`: + +```xml + + + + + + + + + + + + + + +``` + +## 6) Sync Source +```bash +cd ~/crDroid +repo sync --force-sync --no-tags --no-clone-bundle -j$(nproc --all) +``` + +Note: `--force-sync` can discard divergent local checkout states in synced projects. Use it intentionally. + +## 7) Build Execution +Run build with log capture: + +```bash +cd ~/crDroid +export USE_CCACHE=1 +ccache -M 100G +source build/envsetup.sh +brunch 2>&1 | tee build.log +``` + +Build log location: +- `~/crDroid/build.log` + +Fallback build flow (if `brunch` is not available in your tree): + +```bash +cd ~/crDroid +source build/envsetup.sh +lunch -userdebug +m bacon 2>&1 | tee build.log +``` + +## 8) Verify Build Success +### Success criteria +- `brunch ` exits successfully (exit code `0`) +- No fatal `FAILED:` errors at end of build +- Artifacts appear in `out/target/product//` +- Final flashable zip exists (`crDroid*.zip`) + +### Verification commands +```bash +ls -lh out/target/product// +ls -lt out/target/product//crDroid*.zip +sha256sum out/target/product//crDroid*.zip +``` + +## 9) Troubleshooting Common Build Errors +### Standard triage flow +```bash +cd ~/crDroid +repo sync --force-sync --no-tags --no-clone-bundle -j$(nproc --all) +source build/envsetup.sh +brunch 2>&1 | tee build.log +grep -nE "FAILED:|error:|ninja: build stopped" build.log +``` + +Always fix the **first real error** (later errors are often cascades). + +### Frequent failures and fixes +- **`repo sync` fetch/network failures** + - Retry with lower parallelism: + ```bash + repo sync --force-sync --no-tags --no-clone-bundle -j1 + ``` +- **Missing module / `No rule to make target`** + - Usually missing or incorrect local manifest entries. + - Verify device/kernel/vendor repos and branch revision consistency. +- **Generic `ninja: build stopped: subcommand failed`** + - Wrapper error only; inspect first compiler/linker error above it. +- **OOM / process `Killed`** + - Reduce build job count: + ```bash + export NINJA_ARGS="-j8 -l8" + brunch + ``` +- **Disk/inode exhaustion** + ```bash + df -h + df -i + ``` + +### Last-resort source reset +```bash +cd ~/crDroid +repo forall -vc "git reset --hard && git clean -fdx" +repo sync --force-sync --no-tags --no-clone-bundle -j$(nproc --all) +``` + +## 10) Clean Build Procedures +Apply cleanup in this order (least destructive to most destructive). + +### 10.1 Light clean (recommended first) +```bash +cd ~/crDroid +source build/envsetup.sh +m installclean +brunch +``` + +### 10.2 Device-output clean +```bash +cd ~/crDroid +rm -rf out/target/product/ +source build/envsetup.sh +brunch +``` + +### 10.3 Full output clean +```bash +cd ~/crDroid +rm -rf out +source build/envsetup.sh +brunch +``` + +### 10.4 Deep cache clean (`ccache`) +```bash +ccache -C +ccache -M 100G +cd ~/crDroid +source build/envsetup.sh +brunch +``` + +### 10.5 Recommended recovery order +1. Re-sync + rebuild +2. `m installclean` +3. Delete `out/target/product/` +4. Delete full `out/` +5. Clear `ccache` +6. Hard reset repos + full sync + +## 11) Quick Daily Build Loop +```bash +cd ~/crDroid +repo sync --force-sync --no-tags --no-clone-bundle -j$(nproc --all) +source build/envsetup.sh +brunch +ls -lt out/target/product//crDroid*.zip +```