A-Team-Android_ROM_Builder/README.md

# A-Team Android ROM Builder

A-Team Android ROM Builder is a Linux desktop application for managing Android ROM development projects through a GTK-based graphical interface.

The application provides a front end for the repetitive parts of ROM development—project selection, device configuration, ROM configuration, source synchronization, build selection, build execution, tools, terminals, remote hosts, profiles, and updates—while the actual Android operations remain primarily in Bash scripts.

## Features

- GTK 3 desktop GUI
- Build Setup workflow
- Device selection from configuration files
- ROM source and Android-version selection
- Build variant, GApps, clean, installer, ccache, APN, and job-count options
- Build command dropdown driven by `configs/rom_build_commands.conf`
- Project Profiles
- Local and SSH build hosts
- Device source synchronization
- MindTheGapps synchronization
- Build execution through the script layer
- Embedded VTE terminal
- Terminal copy/paste support
- Resource Monitor
- Splash and launcher tools
- Desktop launcher creation
- ROM cleaning
- Updater with staged progress/status reporting
- Update popup changelog display from the update JSON
- Cyan, bold updater status text for easier visibility

## Requirements

The builder is intended for Linux and requires the Python/GTK stack used by the application plus the tools required by the selected ROM.

Typical requirements include:

- Python 3
- GTK 3
- PyGObject (`gi`)
- VTE 2.91
- Bash
- Git
- Android ROM build dependencies
- `btop` or `bpytop` for the resource monitor
- Git LFS where required by the selected source
- OpenSSH client for SSH build hosts

## Running the Builder

Run the application from its project directory:

```bash
python3 gui.py
```

The application expects its configuration, scripts, profiles, and supporting files relative to the builder installation.

## Configuration Layout

```text
A-Team-Android_ROM_Builder/
├── builder/
├── configs/
│   ├── devices/
│   ├── a_team_setup.conf
│   ├── hosts.conf
│   ├── rom.conf
│   ├── rom_build_commands.conf
│   └── upload_services.conf
├── profiles/
├── scripts/
├── gui.py
├── README.md
└── README-TECHNICAL.md
```

## Device Configuration

Devices are discovered from:

```text
configs/devices/*.conf
```

A device normally defines values such as:

```text
DEVICE_CODENAME
DEVICE_DISPLAY_CODENAME
DEVICE_DISPLAY_NAME
DEVICE_MANUFACTURER
DEVICE_MODEL_NUMBER
DEVICE_SYNC_SCRIPT
```

Example:

```text
DEVICE_CODENAME="milanf"
DEVICE_DISPLAY_CODENAME="Milanf"
DEVICE_DISPLAY_NAME="Moto G Stylus 5G 2022"
DEVICE_MANUFACTURER="Motorola"
DEVICE_MODEL_NUMBER="XT2215"
DEVICE_SYNC_SCRIPT="milanf-sync.sh"
```

The device configuration also provides the variables needed by that device's synchronization and build scripts.

## ROM Configuration: `rom.conf`

There are two supported locations for ROM configuration.

### Builder default

```text
configs/rom.conf
```

### ROM-local configuration

```text
<ROM_ROOT>/rom.conf
```

The ROM-local file is preferred when it exists. This lets a ROM source tree carry settings specific to that ROM without requiring the builder-wide configuration to be changed.

Linux filenames are case-sensitive. The loader expects the filename:

```text
rom.conf
```

A dropdown entry may be displayed as:

```text
Default --> rom.conf
```

but the actual file is still the lowercase `rom.conf`.

Typical ROM configuration values include:

```text
ROM_BUILD_NAME
ROM_TARGET_RELEASE
DEFAULT_ROM_BUILD_COMMAND
ROM_DISPLAY_NAME
ROM_VENDOR_NAME
ROM_MANIFEST
ROM_BRANCH_PREFIX
ROM_MAJOR_VERSION
ROM_MINOR_VERSION
```

## Build Commands

Build commands are listed in:

```text
configs/rom_build_commands.conf
```

Example:

```text
Default --> rom.conf
Lineage
Derpfest
```

The selected command becomes the project's build-command value and is consumed by the build-options script.

The command-selection logic is implemented in:

```text
scripts/build_options/rom_build_commands.sh
```

The current function is:

```bash
rom_build_commands()
```

It supports:

- `lineage`
- `derpfest`
- the default command from `rom.conf`

## Build Setup

Build Setup combines project configuration into the environment used by the scripts.

The main selections include:

- Build Host
- Device
- ROM Source
- Android Version
- Build Variant
- GApps Variant
- Clean Variant
- Installer Variant
- Build Jobs
- Ccache
- Custom APN
- Project Profile

The interface also exposes centralized layout constants for spacing and button widths so the UI can be tuned without changing individual widget construction.

## Sync & Setup Device Source

The synchronization workflow is script-driven.

The common entry point is:

```text
scripts/sync.sh
```

Device-specific synchronization scripts are stored under:

```text
scripts/devices_sync/
```

The device configuration selects the appropriate script with:

```text
DEVICE_SYNC_SCRIPT
```

This keeps device-specific setup out of the main GUI.

## MindTheGapps

GApps synchronization is handled by:

```text
scripts/gapps_sync.sh
```

The script selects the appropriate source branch based on the configured Android version and places the resulting GApps source under the ROM tree's expected vendor location.

## Build

The Build tab uses the selected build command and project environment to invoke:

```text
scripts/build.sh
```

The build script sources the ROM build-command function:

```bash
source "$BUILD_OPTIONS_DIR/rom_build_commands.sh"
rom_build_commands
```

This is important because `LUNCH_COMMAND` and `ROM_BUILD_COMMAND` must remain available to the calling build shell.

The selected commands ultimately produce values such as:

```text
LUNCH_COMMAND
ROM_BUILD_COMMAND
```

which the build script executes.

## Terminal

The application includes an embedded VTE terminal.

The terminal accepts normal shell input and now supports copying terminal output out to the desktop clipboard as well as pasting clipboard content into the terminal.

The terminal is intended to remain a normal interactive shell, so regular terminal keyboard behavior is preserved.

## Resource Monitor

The Resource Monitor uses `btop` when available and falls back to `bpytop`.

It is useful during Android builds for watching CPU, memory, storage, and other system resources.

## Tools

The Tools area provides utility functions such as:

- Splash selection
- Launcher icon selection
- Desktop launcher creation
- ROM cleaning

## Project Profiles

Profiles store reusable project selections so recurring device/ROM builds do not need to be configured manually every time.

Profiles are stored under:

```text
profiles/
```

A profile represents project selections; device and ROM configuration files remain the authoritative source for device- and ROM-specific variables.

## Build Hosts

Hosts are configured in:

```text
configs/hosts.conf
```

The builder supports local execution and SSH-based remote hosts.

A remote host must already have the Android build environment and source prerequisites required by the selected ROM.

## Updater

The updater is divided between the Python updater implementation, the GTK updater UI, and:

```text
scripts/updater.sh
```

The shell updater reports staged progress using:

```text
::PROGRESS::<current>::<total>
::STATUS::<message>
```

The GUI converts those messages into the updater progress display.

The update dialog also reads:

```json
"changelog": "..."
```

from the update JSON and displays it with the available and installed versions.

Updater status text is displayed **cyan and bold** for improved visibility.

## Development

For architecture, configuration formats, device addition, build flow, updater protocol, terminal implementation, and extension guidance, see:

```text
README-TECHNICAL.md
```

## License

GNU General Public License v3.0 (GPL-3.0).

**2019-Present — A-Team Digital Solutions**