docs: Document system source formats

README.md

@@ -11,7 +11,7 @@ This tool automates the following tasks for devices that mostly run AOSP out-of-
 - Downloading factory images and full OTA packages
 - Generating a list of **proprietary files**
 - Resolving overridden build rules and **building modules from source** (when possible)
-- Extracting, converting, and mounting **factory images**
+- Extracting, converting, and mounting **factory images** [(supported source formats)](docs/system-source.md)
 - Extracting proprietary files
 - Extracting bootloader and radio **firmware**
 - Finding and adding missing system **properties**
@@ -70,6 +70,7 @@ yarn global add adevtool
 - [Bringing up a new Pixel device](docs/pixel-bringup.md)
 - [Generating or updating an existing device](docs/pixel-generate.md)
 - [Using individual helper commands](docs/commands.md)
+- [Supported system source formats](docs/system-source.md)
 
 ## License
 

docs/commands.md

@@ -2,6 +2,8 @@
 
 This documents individual adevtool commands, most of which can be used independently without a config or full device bringup.
 
+All commands that accept stock system images, with the exception of comparison commands (diff-files, diff-props, diff-vintf), support [the source formats listed here](system-source.md).
+
 ## Extract proprietary files
 
 Given a device codename, vendor name, stock system source, and LineageOS proprietary-files.txt list, extract proprietary files and generate build files.

docs/pixel-bringup.md

@@ -6,6 +6,8 @@ This guide is only for initial bringup; see [Generating or updating an existing
 
 Most commands should be run at the root of your ROM tree, so `aapt2` and other files can be discovered automatically.
 
+All commands that accept stock system images, with the exception of comparison commands (diff-files, diff-props, diff-vintf), support [the source formats listed here](system-source.md).
+
 ## 1. Download factory images
 
 In order to extract proprietary files and other data, you need a copy of the stock ROM for your device. Download the latest factory images package for your device, replacing `raven` with your device's codename:

docs/pixel-generate.md

@@ -6,6 +6,8 @@ While the focus of this guide is on a single device, examples are also shown for
 
 Most commands should be run at the root of your ROM tree, so `aapt2` and other files can be discovered automatically.
 
+All commands that accept stock system images, with the exception of comparison commands (diff-files, diff-props, diff-vintf), support [the source formats listed here](system-source.md).
+
 ## 1. Download factory images
 
 In order to extract proprietary files and other data, you need a copy of the stock ROM for your device. Download the latest factory images package for your device, replacing `raven` with your device's codename:

docs/system-source.md

@@ -0,0 +1,21 @@
+# System source formats
+
+Many adevtool commands require stock system images to introspect and extract files from. You can supply these in many different formats:
+
+- Directory containing mounted partitions (system/, vendor/, etc.)
+- Directory containing extracted factory images package
+- Dircetory containing sparse or raw partition images (system.img, vendor.img, etc.)
+- Factory images package (e.g. raven-sq1d.220105.007-factory-d8f6b8a4.zip)
+- Fastboot update images (nested ZIP extracted from factory images, e.g. image-raven-sq1d.220105.007.zip)
+- Full OTA package (WIP)
+- payload.bin from a full OTA package (WIP)
+
+More flexible sources that can contain multiple devices and builds are also supported, including directories containing any of the above formats...
+
+- Directly in the directory (e.g. `$SRC/raven-sq1d.220105.007-factory-d8f6b8a4.zip`)
+- Under the build ID (e.g. `$SRC/sq1d.220105.007/raven-sq1d.220105.007-factory-d8f6b8a4.zip`)
+- Under the device name (e.g. `$SRC/raven/raven-sq1d.220105.007-factory-d8f6b8a4.zip`)
+- Under the device name and build ID (e.g. `$SRC/raven/sq1d.220105.007/raven-sq1d.220105.007-factory-d8f6b8a4.zip`)
+- Under the build ID and device name (e.g. `$SRC/sq1d.220105.007/raven/raven-sq1d.220105.007-factory-d8f6b8a4.zip`)
+
+All commands that accept stock system images, with the exception of comparison commands (diff-files, diff-props, diff-vintf), support all of the source formats listed above. Make sure to pass the build ID as an argument (`-b` or `--buildId`) to enable support for directories containing build IDs.