Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion docs/INSTALL-GUIDED.md
Original file line number Diff line number Diff line change
Expand Up @@ -99,7 +99,7 @@ Details that matter:
- **Step 1** asks for every program the later steps run, so a missing one
stops the install before the phone is erased, not after: `fastboot`,
`debugfs`, `dumpe2fs`, `e2fsck`, `zstd`, `lz4`, `cpio`, `openssl`, `gpg`,
`python3`, `unzip`, `ssh`, `sha256sum`, `tar`, and for step 9's extract
`python3`, `unzip`, `ssh`, `sha256sum`, `tar`, `img2simg`, and for step 9's extract
tools `lpunpack`, `simg2img`, `fsck.erofs` and `readelf` (or
`llvm-readelf`). The stop names each missing program with its package on
Arch Linux (and Omarchy) and on Debian and Ubuntu (a table in the
Expand Down
2 changes: 1 addition & 1 deletion docs/INSTALL.md
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,7 @@ It takes about an hour, most of it downloads and waiting. **New to this? Use [th
sudo pacman -S --needed android-tools e2fsprogs zstd lz4 cpio openssl gnupg python unzip binutils erofs-utils
```

On other distributions, install the packages with the same names (Android's tools are often split into `fastboot`, `adb` and a "libsparse" package for `img2simg` and `simg2img`).
On other distributions, install the packages with the same names. Android's tools are often split into `fastboot`, `adb` and a "libsparse" package for `img2simg` and `simg2img` (`android-sdk-libsparse-utils` on Debian and Ubuntu), and the installer needs `img2simg`: Google's platform-tools download doesn't have it.
- **Free disk space:** about 35 GB (the downloads, Google's factory image and a working copy of the system image while installing).
- **An SSH key.** The installer puts your public key on the phone so your computer can reach it over USB later. If `~/.ssh/id_ed25519.pub` doesn't exist, make one:

Expand Down
12 changes: 8 additions & 4 deletions tests/install-guided
Original file line number Diff line number Diff line change
Expand Up @@ -41,7 +41,7 @@ pass() { printf 'ok - %s\n' "$1"; }
# skipped every case here (as every run did while the workflow installed no
# unzip) says nothing. Elsewhere the skip is said on both streams, with
# what it leaves unchecked.
for tool in debugfs mkfs.ext4 zstd openssl lz4 cpio gpg unzip python3 curl; do
for tool in debugfs mkfs.ext4 zstd openssl lz4 cpio gpg unzip python3 curl img2simg; do
command -v $tool >/dev/null && continue
if [[ -n ${CI:-}${GITHUB_ACTIONS:-} ]]; then
echo "not ok - tests/install-guided can't run in CI: no $tool (add it to .github/workflows/checks.yml)" >&2
Expand Down Expand Up @@ -1688,9 +1688,13 @@ done
printf 'NAME="Arch Linux"\nID=arch\n' > "$t/os-arch"
printf 'NAME="Ubuntu"\nID=ubuntu\nID_LIKE=debian\n' > "$t/os-ubuntu"
printf 'NAME="Other"\nID=other\n' > "$t/os-other"
# missing ARCH-PACKAGE DEBIAN-PACKAGE (Debian's "-": none we know of)
for spec in "lpunpack android-tools -" "simg2img android-tools android-sdk-libsparse-utils" "fsck.erofs erofs-utils erofs-utils" "readelf binutils binutils"; do
# missing ARCH-PACKAGE DEBIAN-PACKAGE (Debian's "-": none we know of).
# img2simg is this computer's own (the installer runs it), so its link goes
# for its own turn only
real_img2simg=$(readlink -f "$t/sys/img2simg")
for spec in "lpunpack android-tools -" "simg2img android-tools android-sdk-libsparse-utils" "img2simg android-tools android-sdk-libsparse-utils" "fsck.erofs erofs-utils erofs-utils" "readelf binutils binutils"; do
read -r missing arch deb <<<"$spec"
ln -sfn "$real_img2simg" "$t/sys/img2simg"; [[ $missing != img2simg ]] || rm -f "$t/sys/img2simg"
rm -f "$t/sys/lpunpack" "$t/sys/simg2img" "$t/sys/fsck.erofs" "$t/sys/readelf" "$t/sys/llvm-readelf"
mkdir -p "$t/extract-some"; rm -f "$t/extract-some/"*
for c in lpunpack simg2img fsck.erofs readelf; do [[ $c == "$missing" ]] || cp "$t/extract-bin/$c" "$t/extract-some/"; done
Expand All @@ -1714,7 +1718,7 @@ for spec in "lpunpack android-tools -" "simg2img android-tools android-sdk-libsp
[[ $(tail -n 1 "$t/out") == " tools/install-guided "* ]] || fail "a missing $missing: the stop ends with the command to run once it is installed"
done
done
pass "a program a later step needs (lpunpack, simg2img, fsck.erofs, readelf) stops the install at step 1, named with its package on Arch and on Debian and Ubuntu, and the one install command for this system"
pass "a program a later step needs (lpunpack, simg2img, img2simg, fsck.erofs, readelf) stops the install at step 1, named with its package on Arch and on Debian and Ubuntu, and the one install command for this system"

# --- The real tools/phone-provision takes what the installer hands it ---------------
# Everywhere above phone-provision is a stub, and a stub accepts anything:
Expand Down
23 changes: 18 additions & 5 deletions tests/install-phone
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ cd -- "$(dirname -- "${BASH_SOURCE[0]}")/.."
SRC=$PWD
fail() { printf 'not ok - %s\n' "$1" >&2; exit 1; }
pass() { printf 'ok - %s\n' "$1"; }
for tool in debugfs mkfs.ext4 zstd openssl lz4 cpio timeout; do command -v $tool >/dev/null || { echo "skip: no $tool"; exit 0; }; done
for tool in debugfs mkfs.ext4 zstd openssl lz4 cpio timeout img2simg simg2img; do command -v $tool >/dev/null || { echo "skip: no $tool"; exit 0; }; done
t=$(mktemp -d)
cleanup() {
[[ ! -d $t/gnupg ]] || gpgconf --homedir "$t/gnupg" --kill gpg-agent 2>/dev/null || true
Expand Down Expand Up @@ -195,6 +195,23 @@ install() {
flashing_calls() { grep -v -E '^(devices|-s FAKE123 getvar all)$' "$t/fastboot.log" || true; }

vars "" "" $'version-bootloader-a:cloudripper-17.0-15199429\nversion-bootloader-b:cloudripper-17.0-15199429'
# Too little room in --work for the sparse copy: refused before any flash.
real_df=$(command -v df)
cat > "$t/bin/df" <<DF
#!/bin/sh
if [ "\${SPARSE_TEST_LOW_SPACE:-0}" = 1 ]; then
printf 'Filesystem 1024-blocks Used Available Capacity Mounted on\nfixture 100 99 1 99%% /fixture\n'
else
exec "$real_df" "\$@"
fi
DF
chmod +x "$t/bin/df"
SPARSE_TEST_LOW_SPACE=1 install --dry-run && fail "too little room for the sparse copy is refused"
grep -c 'the sparse copy needs' "$t/out" >/dev/null || { cat "$t/out"; fail "the refusal names the room the sparse copy needs"; }
[[ -z $(flashing_calls) ]] || fail "too little room flashes nothing: $(flashing_calls)"
[[ -z $(ls "$t/work") ]] || fail "a refusal for room removes the image copy"
pass "too little room in --work for the sparse copy: refused, nothing flashed, the copy removed"

install --dry-run || { cat "$t/out"; fail "a dry run succeeds"; }
expected=" would run: fastboot -s FAKE123 flash boot_b $t/images/boot.img
would run: fastboot -s FAKE123 flash init_boot_b $t/images/init_boot.img
Expand All @@ -204,7 +221,6 @@ expected=" would run: fastboot -s FAKE123 flash boot_b $t/images/boot.img
would run: fastboot -s FAKE123 flash userdata $t/work/root.simg
would run: fastboot -s FAKE123 --set-active=b
would run: fastboot -s FAKE123 reboot"
command -v img2simg >/dev/null || expected=${expected//root.simg/root.img}
[[ $(grep 'would run:' "$t/out") == "$expected" ]] || { grep 'would run:' "$t/out"; fail "the dry run prints exactly the allowed commands"; }
[[ -z $(flashing_calls) ]] || fail "a dry run only reads variables: $(flashing_calls)"
grep -qF 'correct horse' "$t/out" && fail "the Wi-Fi password is never printed"
Expand All @@ -228,7 +244,6 @@ want="-s FAKE123 flash boot_b $t/images/boot.img
-s FAKE123 flash userdata $t/work/root.simg
-s FAKE123 --set-active=b
-s FAKE123 reboot"
command -v img2simg >/dev/null || want=${want//root.simg/root.img}
[[ $(flashing_calls) == "$want" ]] || { flashing_calls; fail "a run sends exactly the allowed commands"; }
grep -c 'bootloader cloudripper-17.0-15199429 on both slots$' "$t/out" >/dev/null || fail "per-slot versions from the phone are compared as they are"
pass "full run: fastboot gets exactly slot B's images, userdata, set-active b, reboot (per-slot versions reported: no slot round trip)"
Expand Down Expand Up @@ -1065,7 +1080,6 @@ expected=" would run: fastboot -s FAKE123 flash boot_a $t/images2/boot.img
would run: fastboot -s FAKE123 flash dtbo_a $t/images2/dtbo.img
would run: fastboot -s FAKE123 flash userdata $t/work/root.simg
would run: fastboot -s FAKE123 reboot"
command -v img2simg >/dev/null || expected=${expected//root.simg/root.img}
[[ $(grep 'would run:' "$t/out") == "$expected" ]] || { grep 'would run:' "$t/out"; fail "a format 2 dry run prints slot a's images, userdata and reboot, nothing else"; }
[[ -z $(flashing_calls) ]] || fail "a format 2 dry run only reads variables: $(flashing_calls)"
grep -c 'Android on this phone is REPLACED' "$t/out" >/dev/null && grep -c "Google's factory image" "$t/out" >/dev/null ||
Expand All @@ -1082,7 +1096,6 @@ want="-s FAKE123 flash boot_a $t/images2/boot.img
-s FAKE123 flash dtbo_a $t/images2/dtbo.img
-s FAKE123 flash userdata $t/work/root.simg
-s FAKE123 reboot"
command -v img2simg >/dev/null || want=${want//root.simg/root.img}
[[ $(flashing_calls) == "$want" ]] || { flashing_calls; fail "a format 2 run sends exactly slot a's images, userdata and reboot"; }
[[ $(grep -c '^-s FAKE123 getvar all$' "$t/fastboot.log") == 3 ]] || fail "the phone is read three times: the first look, the gate before the first flash, the read-back"
grep -c 'Done. The phone starts Omarchy Mobile from slot a' "$t/out" >/dev/null || fail "a format 2 run ends with the slot it wrote"
Expand Down
2 changes: 1 addition & 1 deletion tests/install-phone-initramfs
Original file line number Diff line number Diff line change
Expand Up @@ -37,7 +37,7 @@ PKG=$SRC/packages/omamobile-boot-update
fail() { printf 'not ok - %s\n' "$1" >&2; exit 1; }
pass() { printf 'ok - %s\n' "$1"; }
skip() { printf 'ok - # skip: %s\n' "$1"; exit 0; }
for tool in lz4 cpio dtc debugfs mkfs.ext4 zstd openssl python3 flock; do command -v $tool >/dev/null || skip "no $tool"; done
for tool in lz4 cpio dtc debugfs mkfs.ext4 zstd openssl python3 flock img2simg; do command -v $tool >/dev/null || skip "no $tool"; done
t=$(mktemp -d)
trap '[[ -n ${KEEP:-} ]] || rm -rf "$t"' EXIT

Expand Down
6 changes: 4 additions & 2 deletions tools/install-guided
Original file line number Diff line number Diff line change
Expand Up @@ -558,6 +558,7 @@ PACKAGES=(
"tar tar tar"
"lpunpack android-tools -"
"simg2img android-tools android-sdk-libsparse-utils"
"img2simg android-tools android-sdk-libsparse-utils"
"fsck.erofs erofs-utils erofs-utils"
"readelf binutils binutils"
)
Expand Down Expand Up @@ -598,11 +599,12 @@ step_preflight() {
title preflight
# Every program a later step runs, asked for now: one that is missing must
# stop the install here, not after the phone has been erased. The writes
# (tools/install-phone), the radio backup (tools/nv-backup) and the
# (tools/install-phone, which needs img2simg for the sparse userdata
# image), the radio backup (tools/nv-backup) and the
# firmware (tools/phone-provision and the extract tools it runs: lpunpack,
# simg2img, fsck.erofs, debugfs, readelf).
for t in "$FASTBOOT" debugfs dumpe2fs e2fsck zstd lz4 cpio openssl gpg python3 unzip ssh sha256sum \
tar lpunpack simg2img fsck.erofs; do
tar img2simg lpunpack simg2img fsck.erofs; do
command -v "$t" >/dev/null || missing+=("${t##*/}")
done
command -v readelf >/dev/null || command -v llvm-readelf >/dev/null || missing+=(readelf)
Expand Down
34 changes: 22 additions & 12 deletions tools/install-phone
Original file line number Diff line number Diff line change
Expand Up @@ -78,9 +78,11 @@
# image for this device in out/, or the exact
# image named by a signed bundle's MANIFEST)
# --work DIR where the local image copy goes (default
# ~/.cache/omamobile-install; needs the image's
# size free). The next run that finds no other
# run live removes killed runs' verify.*
# ~/.cache/omamobile-install; needs room for the
# image's used blocks twice, the copy and its
# sparse conversion, plus 1 GiB). The next run
# that finds no other run live removes killed
# runs' verify.*
# directories; ones left by installers without
# this cleanup are kept
# --bootloader-slots-match VERSION
Expand Down Expand Up @@ -281,8 +283,8 @@ if [[ $mode == repository ]]; then
[[ $built_for == "$CODENAME" ]] \
|| die "$images holds images for '${built_for:-an unknown device}', not $CODENAME (run: DEVICE=$CODENAME bin/omamobile images)"
fi
for tool in "$FASTBOOT" debugfs dumpe2fs e2fsck zstd openssl sha256sum lz4 cpio python3 timeout; do
command -v "$tool" >/dev/null || die "$tool not found (fastboot: android-tools; debugfs: e2fsprogs; lz4: lz4; cpio: cpio)"
for tool in "$FASTBOOT" debugfs dumpe2fs e2fsck img2simg zstd openssl sha256sum lz4 cpio python3 timeout; do
command -v "$tool" >/dev/null || die "$tool not found (fastboot, img2simg: android-tools, or fastboot and android-sdk-libsparse-utils on Debian and Ubuntu; debugfs: e2fsprogs; lz4: lz4; cpio: cpio)"
done
BOOT_IMAGES=${D[BOOT_IMAGES]:-} UFS_RW=${D[UFS_RW]:-}
[[ -n $BOOT_IMAGES && -n $UFS_RW ]] || die "$conf: BOOT_IMAGES and UFS_RW are required"
Expand Down Expand Up @@ -1200,13 +1202,21 @@ cmp -s <(debugfs -R "cat /root/.ssh/authorized_keys" "$copy" 2>/dev/null) "$keys
cmp -s <(debugfs -R "cat /etc/omamobile/boot-update.conf" "$copy" 2>/dev/null) "$boot_conf" || die "writing boot-update.conf into the image copy failed"
e2fsck -fn "$copy" >/dev/null 2>&1 || die "the image copy doesn't check clean after the writes"
note "firstboot.conf, root's authorized_keys and boot-update.conf (AUTO_WRITE=$BOOT_UPDATE_AUTO_WRITE$( ((fmt == 1)) || printf ', SLOT=%s' "$target")) written, file system checks clean"
userdata_image=$copy
if command -v img2simg >/dev/null; then
img2simg "$copy" "$sparse"
rm -f "$copy"
userdata_image=$sparse
note "converted to an Android sparse image ($(du -h "$sparse" | cut -f1))"
fi
# userdata is always flashed as an Android sparse image: one path, the one
# the dry run prints. The sparse copy takes about the raw copy's used blocks
# (decompressed with --sparse, so far fewer than its apparent size): check
# for that much free plus 1 GiB rather than let img2simg run out of room.
used_bytes=$(du -k "$copy" | awk '{printf "%.0f\n", $1 * 1024}')
free_bytes=$(df -Pk "$work" | awk 'NR == 2 {printf "%.0f\n", $4 * 1024}')
[[ $used_bytes =~ ^[0-9]+$ && $free_bytes =~ ^[0-9]+$ ]] ||
die "can't tell the image copy's size or the free space in $work"
need=$((used_bytes + 1073741824))
((free_bytes >= need)) ||
die "$work has $free_bytes bytes free; the sparse copy needs $need (give a --work DIR on a larger file system)"
img2simg "$copy" "$sparse" || die "img2simg failed to convert the image copy in $work"
rm -f "$copy"
userdata_image=$sparse
note "converted to an Android sparse image ($(du -h "$sparse" | cut -f1))"

# --- The owner's key in slot B's initramfs -----------------------------------
# omamobile-boot-update builds slot B's ramdisk with root's authorized_keys
Expand Down
2 changes: 1 addition & 1 deletion tools/make-bundle
Original file line number Diff line number Diff line change
Expand Up @@ -303,7 +303,7 @@ needs you. Run it again after any stop: it goes on from there.
Install by hand: put the phone in fastboot mode (bootloader unlocked),
connect it, and run "bash install" from this directory ("bash install"
works even when a download lost the file's execute bit). It needs fastboot
(android-tools), e2fsprogs, zstd, lz4, cpio, openssl, gpg and python3 on
and img2simg (android-tools), e2fsprogs, zstd, lz4, cpio, openssl, gpg and python3 on
this computer. The installer checks the phone first, asks for your user
name, password, Wi-Fi and SSH key, shows exactly what it will write, and
waits for you to type "$DEVICE".
Expand Down