Skip to content

install-phone: always flash userdata sparse, with room checked first - #877

Merged
derekross merged 3 commits into
derekross:mainfrom
kdegeek:tools-installer-sparse
Nov 18, 2026
Merged

derekross merged 3 commits into
derekross:mainfrom
kdegeek:tools-installer-sparse

Conversation

@kdegeek

@kdegeek kdegeek commented Nov 18, 2026

Copy link
Copy Markdown
Contributor

What and why

tools/install-phone flashed userdata as an Android sparse image when img2simg was installed, and as the raw image otherwise. The same install therefore took two paths depending on the host, and the dry run's printed commands changed with them. img2simg also ran unchecked. On a work directory without room for the sparse copy it failed part way, after the image copy had been prepared.

  • img2simg is now required with the other tools. It comes from android-tools, like fastboot, and CI already installs it.
  • userdata is always flashed as the sparse image.
  • Before converting, the installer checks that --work has room for the copy's used blocks plus 1 GiB. The copy is decompressed with --sparse, so its used blocks are far fewer than its apparent size. Without the room, the installer refuses and prints the numbers.
  • If img2simg fails, the install stops.
  • In both cases nothing is flashed, and the copy is removed as before.
  • The --work help text names the room needed.

Device and build

  • Phone: none: installer on the computer. The change is on the computer's side, before any fastboot write; the commands sent are the ones a host with img2simg already sent.
  • Kernel release: n/a
  • Packages changed: none

Checks (no phone needed)

  • tools/pr-check upstream/main passes
  • tests/install-phone: passes
    • img2simg and simg2img join its required tools, and the raw-image fallbacks in the expected commands go.
    • A df that reports no room checks the refusal: the room is named, nothing is flashed and no copy is left behind.
  • tests/install-phone-initramfs, tests/install-guided, tests/boot-method, tests/install-slot-descriptor: all pass. The first two run the real installer, and they now skip without img2simg, as they do without its other tools.
  • bash -n and shellcheck -S warning on the touched scripts: no new warnings against main
  • Full tests/all: not run, only the installer tests above

On the phone

  • Not run against a phone for this PR. Fastboot was faked in every test.
  • The flashed partitions are unchanged: slot B's images and userdata only.

🤖 Generated with Claude Code

The installer flashed userdata as an Android sparse image when img2simg
was installed and as the raw image otherwise, so the same command took
two different paths depending on the host, and the dry run's printed
commands changed with it. img2simg also ran unchecked: on a work
directory without room for the sparse copy it failed part way, after
the image copy had been prepared.

img2simg is now required with the other tools (from android-tools, like
fastboot, and already in CI), and userdata is always the sparse image.
Before converting, the installer checks that --work has the raw copy's
used blocks (it is decompressed with --sparse, so far fewer than its
apparent size) plus 1 GiB free, and refuses with the numbers if not; a
failing img2simg stops the install. Nothing is flashed in either case,
and the copy is removed as before.

tests/install-phone: img2simg and simg2img join the required tools, the
raw-image fallbacks in the expected commands go, and a df that reports
no room checks the refusal: no flash and no copy left behind.
tests/install-phone-initramfs and tests/install-guided, which run the
real installer, skip without img2simg as they do without its other
tools.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@derekross

Copy link
Copy Markdown
Owner

Thank you, @kdegeek. I went through this one slowly because it is the installer, and the result is good: on a computer with img2simg the phone gets exactly the commands and files it gets from main, the new refusals (no img2simg, too little room) both come before anything is written, and the cleanup removes the copy, as your test checks. The sparse path is the one every install from an Omarchy laptop already takes, so nothing here needs a run on a phone. On your branch merged with today's main, tests/install-phone (41), tests/install-guided (53), tests/boot-method, tests/make-bundle and tests/install-slot-descriptor pass, and removing the room check fails your new case. (tests/install-phone-initramfs skips on my laptop for want of dtc; CI will run it.)

What I'd like before merging: img2simg is now required, so the places that tell an owner what the install needs should say so.

  1. tools/install-guided: its preflight is there so a missing program stops the install before anything else does, with the package for it on Arch and on Debian/Ubuntu. Please add "img2simg android-tools android-sdk-libsparse-utils" to PACKAGES, img2simg to the loop in step_preflight, and the same spec to the missing-program loop in tests/install-guided.
  2. tools/install-phone's refusal says fastboot, img2simg: android-tools. That is Arch's package; on Debian and Ubuntu img2simg is in android-sdk-libsparse-utils, and Google's platform-tools download doesn't have it. Someone there has fastboot, could install with main, and would now be told to install what they think they have. Please name both, for example fastboot, img2simg: android-tools (Debian, Ubuntu: fastboot and android-sdk-libsparse-utils).
  3. docs/INSTALL.md ("These programs on the computer") and the bundle's README text in tools/make-bundle ("It needs fastboot (android-tools), …"): add img2simg to the lists.

One more spot of the same kind: tests/install-slot-descriptor runs install-phone --verify-only and has no check for the installer's programs, so with this change it fails on a computer without img2simg (and, I'm told on #882, it already does without fastboot). Please give it the guard the other installer suites got here.

Two smaller things, as you like. The 1 GiB margin: the sparse file can't be larger than the copy's used blocks plus headers, so the gigabyte mostly refuses installs that would have fit; a much smaller margin does the job. And "a failing img2simg stops the install" has no test yet: a stand-in that exits 1 beside your df case would cover it.

I'll approve the CI run now.

@derekross derekross left a comment

Copy link
Copy Markdown
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

CI ran on this head and both jobs pass, including tests/install-phone-initramfs, which I couldn't run on my laptop this morning.

Of the four things I asked for, one is already done on main (tests/install-slot-descriptor got its guard in #893, img2simg included). The other three are small, so I'll push them to your branch myself: img2simg in the guided install's preflight and package table (with a case in its test), the Debian and Ubuntu package in install-phone's "not found" hint, and img2simg in INSTALL.md, INSTALL-GUIDED.md and the bundle's README. With them the installer suites pass on your branch merged with today's main, and the new preflight case fails when I take img2simg out of the loop again. I'll merge when CI is green on that push. If you'd rather make them yourself, say so and I'll wait.

The two optional points (the 1 GiB margin, a test for a failing img2simg) stay optional.

derekross and others added 2 commits November 18, 2026 13:06
The guided install's preflight and package table name img2simg, with a
case in its test; install-phone's hint gives the Debian and Ubuntu package;
INSTALL, INSTALL-GUIDED and the bundle's README list it.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
@derekross
derekross merged commit 39c29b9 into derekross:main Nov 18, 2026
2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants