pmbootstrap, with Synit changes
You cannot select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
Go to file
Oliver Smith 248fe447bd
pmb.chroot.root: set PYTHONUNBUFFERED=1 (MR 2209)
Set the env var, so python programs running inside pmbootstrap chroot
don't buffer their output and only end up printing everything when they
are done. I've seen this with meson. This is bad for usability because
we don't see output, but also a problem because pmbootstrap kills
commands if they don't print any output for some time (default: 15 min).
8 months ago
.ci CI: .gitlab/ -> .ci/ (MR 2080) 2 years ago
helpers Revert "helpers/ add gawk when initialising chroot (MR 2186)" (MR 2188) 11 months ago
pmb pmb.chroot.root: set PYTHONUNBUFFERED=1 (MR 2209) 8 months ago
test pmb.aportgen.gcc: remove !tracedeps option 8 months ago
.gitignore Fix test_aportgen_compare_output (!1727) 5 years ago
.gitlab-ci.yml Revert "CI: download shellcheck (MR 2142)" 2 years ago Fix spelling mistakes (!1794) 4 years ago
LICENSE Initial commit 6 years ago install apk keys and binfmt data with 5 years ago Allow override of SSH key glob: documentation (MR 2167) 1 year ago Happy new year 2022! 1 year ago
setup.cfg flake8: increase the line length limit (MR 2168) 1 year ago enforce E501 in (MR 2058) 2 years ago


Introduction | Security Warning | Devices

Sophisticated chroot/build/flash tool to develop and install postmarketOS.

Package build scripts live in the pmaports repository now.


Usage Examples

Please refer to the postmarketOS wiki for in-depth coverage of topics such as porting to a new device or installation. The help output (pmbootstrap -h) has detailed usage instructions for every command. Read on for some generic examples of what can be done with pmbootstrap.

Installing pmbootstrap


Initial setup:

$ pmbootstrap init

Run this in a second window to see all shell commands that get executed:

$ pmbootstrap log

Quick health check and config overview:

$ pmbootstrap status


Build aports/main/hello-world:

$ pmbootstrap build hello-world

Cross-compile to armhf:

$ pmbootstrap build --arch=armhf hello-world

Build with source code from local folder:

$ pmbootstrap build linux-postmarketos-mainline --src=~/code/linux

Update checksums:

$ pmbootstrap checksum hello-world

Generate a template for a new package:

$ pmbootstrap newapkbuild ""


Enter the armhf building chroot:

$ pmbootstrap chroot -b armhf

Run a command inside a chroot:

$ pmbootstrap chroot -- echo test

Safely delete all chroots:

$ pmbootstrap zap

Device Porting Assistance

Analyze Android boot.img files (also works with recovery OS images like TWRP):

$ pmbootstrap bootimg_analyze ~/Downloads/twrp-3.2.1-0-fp2.img

Check kernel configs:

$ pmbootstrap kconfig check

Edit a kernel config:

$ pmbootstrap kconfig edit --arch=armhf postmarketos-mainline

Root File System

Build the rootfs:

$ pmbootstrap install

Build the rootfs with full disk encryption:

$ pmbootstrap install --fde

Update existing installation on SD card:

$ pmbootstrap install --sdcard=/dev/mmcblk0 --rsync

Run the image in QEMU:

$ pmbootstrap qemu --image-size=1G

Flash to the device:

$ pmbootstrap flasher flash_kernel
$ pmbootstrap flasher flash_rootfs --partition=userdata

Export the rootfs, kernel, initramfs, boot.img etc.:

$ pmbootstrap export

Extract the initramfs

$ pmbootstrap initfs extract

Build and flash Android recovery zip:

$ pmbootstrap install --android-recovery-zip
$ pmbootstrap flasher --method=adb sideload

Repository Maintenance

List pmaports that don't have a binary package:

$ pmbootstrap repo_missing --arch=armhf --overview

Increase the pkgrel for each aport where the binary package has outdated dependencies (e.g. after soname bumps):

$ pmbootstrap pkgrel_bump --auto

Generate cross-compiler aports based on the latest version from Alpine's aports:

$ pmbootstrap aportgen binutils-armhf gcc-armhf

Manually rebuild package index:

$ pmbootstrap index

Delete local binary packages without existing aport of same version:

$ pmbootstrap zap -m


Use -v on any action to get verbose logging:

$ pmbootstrap -v build hello-world

Parse a single deviceinfo and return it as JSON:

$ pmbootstrap deviceinfo_parse pine64-pinephone

Parse a single APKBUILD and return it as JSON:

$ pmbootstrap apkbuild_parse hello-world

Parse a package from an APKINDEX and return it as JSON:

$ pmbootstrap apkindex_parse $WORK/cache_apk_x86_64/APKINDEX.8b865e19.tar.gz hello-world

ccache statistics:

$ pmbootstrap stats --arch=armhf

distccd log:

$ pmbootstrap log_distccd

Use alternative sudo

pmbootstrap supports doas and sudo. If multiple sudo implementations are installed, pmbootstrap will use doas. You can set the PMB_SUDO environmental variable to define the sudo implementation you want to use.

Select SSH keys to include and make authorized in new images

If the config file option ssh_keys is set to True (it defaults to False), then all files matching the glob ~/.ssh/id_*.pub will be placed in ~/.ssh/authorized_keys in the user's home directory in newly-built images.

Sometimes, for example if you have a large number of SSH keys, you may wish to select a different set of public keys to include in an image. To do this, set the ssh_key_glob configuration parameter in the pmbootstrap config file to a string containing a glob that is to match the file or files you wish to include.

For example, a ~/.config/pmbootstrap.cfg may contain:

# ...
ssh_keys = True
ssh_key_glob = ~/.ssh/
# ...


Requirements for running tests

You also need to install the following python packages (pip can be useful if you distribution hasn't got them packaged):

  • pytest
  • pytest-cov
  • flake8

On Alpine Linux it can be done with:

$ sudo apk add grep shellcheck py3-pytest py3-pytest-cov py3-flake8

Running linters

The easiest way is to run the same script CI runs:

$ ./test/

Running tests

You can now run pytest -vv inside the pmbootstrap folder to run all available tests.

CI runs slightly reduces set of tests (it skips tests that require running qemu) by this:

$ .ci/

This is the easiest way to do the same as CI.

Alternatively you can run a single test file if you wish:

$ pytest -vv ./test/