Documentation
Playground GitHub

install, images, package, clean

The verbs that act on an image once build has made it: put it on a phone, list the store, write it out as a file, clean up.

An image is what build produces, by name, in ~/.whitehall/images/. Every verb here takes that name, or a path to build first — a path-shaped argument is source, a bare word is always the store. The rule is on the build page.

install

whitehall install [image | path | .apk] [options]

Put the image on the phone, launchable from the drawer. It is the same image run uses. A tool's launcher entry ships disabled and install enables it; a .wh app's shipped enabled, so there is nothing to toggle and the line says so.

whitehall install .                 # build this directory, then install what came out
whitehall install showcase          # the image called showcase
whitehall install showcase.apk -d pixel   # an APK, straight to the phone
FlagWhat it does
-d, --device <id>Which phone. A serial, the start of one, or the model name
-r, --releaseBuild a release image first. Only for the form that takes a path
--bootStart the program's declared service when the phone boots. Needs a [service] declaration
--no-bootStop starting it at boot. The default for a fresh install

A .apk is already an image, whoever built it, so it goes straight to the phone. -d still picks the device, which is the reason to type this over adb install. --boot, --no-boot and --release are refused on that form: they need a manifest Whitehall generated.

Every image is debuggable="true", because the transport run and install use needs it. An APK from whitehall package handed to a friend is a debuggable APK.

uninstall

whitehall uninstall <image | package> [-d <id>] [--keep-data]

Take one thing off the phone: the image name, or a package name such as com.example.showcase for an app that came from somewhere else. --keep-data leaves the app's data and cache directories behind (pm uninstall -k). The image stays in the store, so whitehall install showcase puts it back without a rebuild.

images

whitehall images [--all]

List the store: name, kind, size and source. Without --all it lists what you built. A REPL session, a python3 -c and a cargo test binary each leave an image behind because the mechanism needs one; -a/--all shows those too, docker ps -a's shape.

package

whitehall package [image | path] [-o <file>] [-r]

Write an image out as <name>.apk, to hand to another phone. This is the one place the .apk extension exists. -o/--out says where; the default is <name>.apk in the current directory.

whitehall package apps/showcase -o showcase.apk
whitehall install showcase.apk -d pixel

For a release signed with the project's own key, see Signing.

clean

whitehall clean [target] [options]

Plain clean belongs to a project, the way cargo clean does: with no whitehall.toml it refuses and does nothing. The global stores are behind --images and --packages and work from anywhere. A bare name instead of a path removes that one image from the store, docker's rmi.

CommandWhat it does
cleanThis project's build output, plus the images nothing can rebuild or nobody asked for
clean <name>Remove that one image from the store
clean --programsUninstall the programs cargo run left on the phone
clean --programs --allAlso the ones install gave an icon
clean --programs -d <id>On this phone
clean --imagesEmpty the image store under ~/.whitehall/images/
clean --packagesEmpty the Termux package cache under ~/.whitehall/packages/
$ whitehall clean --programs
     Removed 7 programs from Pixel
        Kept 1 program on the launcher — `--all` removes those too

push and pull

whitehall push <paths>… and whitehall pull <paths>… are adb push and adb pull with the device resolved. push defaults its destination to /sdcard/; -t/--to sets either side's target. Nothing goes anywhere but the phone plugged in.

See Also