User:knuxify/Draft:pmbootstrap

🚧	This page is a work-in-progress. Some information contained within may be inaccurate or incomplete. In particular: This is a layout for a potential pmbootstrap page rewrite. It's completely empty as of now, but will eventually be filled with more useful information.

pmbootstrap is postmarketOS's dedicated build tool. This page contains a brief explanation of how it works, as well as some tips and tricks for using it.

How it works

pmbootstrap uses chroots, small self-contained installations of postmarketOS (technically Alpine Linux), to manage all build dependencies. This way, the user doesn't have to set up any build dependencies manually, outside of pmbootstrap.

pmbootstrap manages building packages, including cross-compilation, as well as postmarketOS image generation and a few other development tools.

Installing pmbootstrap

Requirements

To run pmbootstrap, you need to be running Linux. Other operating systems are not supported - while some people have succeeded at using WSL (see Windows FAQ#Can I_use pmbootstrap in WSL?), your best option is to set up a Linux install or virtual machine.

Your host system should be running a somewhat recent kernel version (at least newer that v3.17). Note that grsec is not supported.

Installing from a distribution package

Some distributions package pmbootstrap. If your distribution is among them, and the version isn't too outdated, you can usually get the pmbootstrap package from your preferred package manager.

An overview of pmbootstrap versions in various package repositories can be found on Repology.

Installing from git

If your distribution doesn't offer a pmbootstrap package, or if it's outdated, or if you just want the latest development version of pmbootstrap, you can also get it directly from its repository.

$ git clone --depth=1 https://gitlab.com/postmarketOS/pmbootstrap.git
$ mkdir -p ~/.local/bin
$ ln -s "$PWD/pmbootstrap/pmbootstrap.py" ~/.local/bin/pmbootstrap
$ pmbootstrap --version
2.1.0

If this returns something like pmbootstrap: command not found instead of a version number, you may need to add ~/.local/bin to your PATH variable. This can be done by adding the following to your ~/.profile (zsh: ~/.zprofile):

PATH="$HOME/.local/bin:$PATH"

Then open a new terminal (or run source ~/.profile to apply your changes immediately) and try again.

First steps

The first step to working with pmbootstrap is initializing it. You can do this by running:

$ pmbootstrap init

This will display a few prompts that will allow you to select the work path, the device you're developing for and some installation-related settings.

TODO: pmbootstrap init and related options.

Work directory

TODO: talk about work dir layout and what to watch out for

Viewing the log

TODO: explain pmbootstrap log, log file location, what to post when troubleshooting, etc.

Checking the status and updating pmaports

TODO: explain pmbootstrap status and pmbootstrap pull

Installing postmarketOS with pmbootstrap

One of pmbootstrap's main features is the ability to build and flash a postmarketOS image. This section describes some of the useful commands; for a proper guide, see Installation/Using pmbootstrap.

Generating an image

After selecting settings such as the device to build for, the UI to use and pre-installed packages in pmbootstrap init, you can generate an image using:

$ pmbootstrap install

This will prepare a secondary chroot containing the postmarketOS installation and generate a flashable image file that can later be flashed with pmbootstrap flasher (see #Flashing the generated image).

There are various flags that can be passed to pmbootstrap install. The most commonly used ones are as follows:

$ pmbootstrap install --fde # performs an install with full-disk encryption
$ pmbootstrap install --disk /dev/sdx # automatically flashes the generated image to the provided block device; used for e.g. installing to an SD card
$ pmbootstrap install --android-recovery-zip # generates a TWRP-flashable ZIP
$ pmbootstrap install --add package1,package2,package3 # adds packages to install to the generated image

See pmbootstrap install --help for a full list.

Flashing the generated image

The image generated with pmbootstrap install can be flashed to the device with pmbootstrap flasher. There are multiple flasher actions available:

$ pmbootstrap flasher flash_kernel # flash the kernel
$ pmbootstrap flasher flash_rootfs # flash the rootfs
$ pmbootstrap flasher flash_lk2nd # flash lk2nd, a secondary bootloader needed for various Android devices
$ pmbootstrap flasher flash_vbmeta # generate and flash AVB 2.0 image with disable verification flag

The above flasher commands can also take the --partition parameter to specify the target partition to flash to.

Besides flashing images, the pmbootstrap flasher command also has some useful utilities:

$ pmbootstrap flasher list_devices # show connected devices
$ pmbootstrap flasher boot # boot a kernel once without flashing (fastboot only)
$ pmbootstrap flasher sideload # sideload recovery ZIP; only if --android-recovery-zip option was used in pmbootstrap install

For a full list of flasher actions and parameters, see pmbootstrap flasher --help and pmbootstrap flasher ACTION --help (e.g. pmbootstrap flasher flash_rootfs --help).

Exporting images

The image generated by pmbootstrap install can be exported into a temporary directory for easier access:

$ pmbootstrap export

This will create a directory named /tmp/postmarketOS-export.

TODO: explain pmbootstrap export and flashing custom images, pmbootstrap initfs extract

Device porting assistance

TODO: brief mention of the tools, redirect to porting guide

Building packages

TODO: explain pmbootstrap checksum, pmbootstrap build; talk about apkbuild format and link apkbuild reference; pmbootstrap build --src

Creating a new package

TODO: explain pmbootstrap newapkbuild

Forking a package from Alpine

TODO: explain pmbootstrap aportgen

Sideloading built packages

See also: Installing packages on a running phone

Not to be confused with mrtest.

TODO: explain pmbootstrap sideload

Chroot management

TODO: explain pmbootstrap chroot and what each chroot does/is used for; also pmbootstrap shutdown

Entering the chroot

TODO: pmbootstrap chroot intro

Zapping the chroot

TODO: pmbootstrap zap brief intro

Cleaning up

TODO: explain the different prompts and flags for pmbootstrap zap and what they're useful for

Advanced tools

These are mostly useful to postmarketOS maintainers.

Repository maintenance

TODO: pmbootstrap#Repository maintenance

Running CI scripts locally

TODO: pmbootstrap#Running CI scripts locally

Troubleshooting

See also: Troubleshooting#pmbootstrap and build related errors

TODO: call back to pmbootstrap log, help channels, bug reporting, etc.