Yanked

This release has been yanked by its maintainers, and will be ignored by installers, except when explicitly specified.
Reason given by maintainers: Installing pmbootstrap from pypi is deprecated, see: https://postmarketos.org/pmbootstrap

pmbootstrap

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

Development

pmbootstrap is being developed on SourceHut (what):

https://git.sr.ht/~postmarketos/pmbootstrap

Send patches via mail or web UI to pmbootstrap-devel (subscribe):

~postmarketos/pmbootstrap-devel@lists.sr.ht

You can set the default values for sending email in the git checkout

$ git config sendemail.to "~postmarketos/pmbootstrap-devel@lists.sr.ht"
$ git config format.subjectPrefix "PATCH pmbootstrap"

Run CI scripts locally with:

$ pmbootstrap ci

Run a single test file:

$ pytest -vv ./test/test_keys.py

Issues

Issues are being tracked here.

Requirements

Linux distribution on the host system (x86, x86_64, aarch64 or armv7)
- Windows subsystem for Linux (WSL) does not work! Please use VirtualBox instead.
- Linux kernel 3.17 or higher
Python 3.7+
OpenSSL
git
ps
tar

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

https://wiki.postmarketos.org/wiki/Installing_pmbootstrap

Basics

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

Packages

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 "https://gitlab.com/postmarketOS/osk-sdl/-/archive/0.52/osk-sdl-0.52.tar.bz2"

Default architecture

Packages will be compiled for the architecture of the device running pmbootstrap by default. For example, if your x86_64 PC runs pmbootstrap, it would build a package for x86_64 with this command:

$ pmbootstrap build hello-world

If you would rather build for the target device selected in pmbootstrap init by default, then use the build_default_device_arch option:

$ pmbootstrap config build_default_device_arch True

If your target device is pine64-pinephone for example, pmbootstrap will now build this package for aarch64:

$ pmbootstrap build hello-world

Chroots

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 --disk=/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 gcc-armhf

Manually rebuild package index:

$ pmbootstrap index

Delete local binary packages without existing aport of same version:

$ pmbootstrap zap -m

Debugging

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

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:

[pmbootstrap]
# ...
ssh_keys = True
ssh_key_glob = ~/.ssh/postmarketos-dev.pub
# ...

License

GPLv3

Release files for pmbootstrap 2.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for pmbootstrap 2.1.0
File	Size	Uploaded
pmbootstrap-2.1.0.tar.gz	236.7 kB	Dec 3, 2023	Details

Built distribution (wheel)

Table of built distributions (wheels) for pmbootstrap 2.1.0
File	Interpreter	ABI	Platform	Reset
pmbootstrap-2.1.0-py3-none-any.whl 251.9 kB Dec 3, 2023	Python 3	none	any	Details

Total release size: 488.6 kB

Release files / pmbootstrap-2.1.0.tar.gz

Download URL	pmbootstrap-2.1.0.tar.gz
Size	236.7 kB
Tags	Source
SHA-256 checksum How to use checksums	`6ee09f42c8b5d0b7b30f361ea6502b985452737bdb8ed97e16e4e6fd5512daeb`
BLAKE2b-256 checksum How to use checksums	`fe033a2dbcdc5dc080e5221e6a3977331e456820e85e5680c754e38d6f4a8bce`
Upload date	Dec 3, 2023
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/4.0.2 CPython/3.11.6`

Release files / pmbootstrap-2.1.0-py3-none-any.whl

Download URL	pmbootstrap-2.1.0-py3-none-any.whl
Size	251.9 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`c4afd17f73da8ee558c033809bbb6d0c5219c582a17c2859b57938a9090e30e9`
BLAKE2b-256 checksum How to use checksums	`e1f838fb31e149a5ab4294e20f295199614054e5c861c9c2317134f6172dc46c`
Upload date	Dec 3, 2023
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/4.0.2 CPython/3.11.6`