A sophisticated chroot / build / flash tool to develop and install postmarketOS
Reason this release was yanked:
Installing pmbootstrap from pypi is deprecated, see: https://postmarketos.org/pmbootstrap
Project description
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
orarmv7
)- 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
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
File details
Details for the file pmbootstrap-2.1.0.tar.gz
.
File metadata
- Download URL: pmbootstrap-2.1.0.tar.gz
- Upload date:
- Size: 236.7 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/4.0.2 CPython/3.11.6
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 | 6ee09f42c8b5d0b7b30f361ea6502b985452737bdb8ed97e16e4e6fd5512daeb |
|
MD5 | 72352714cb4f72d3cd7adf58325ac235 |
|
BLAKE2b-256 | fe033a2dbcdc5dc080e5221e6a3977331e456820e85e5680c754e38d6f4a8bce |
File details
Details for the file pmbootstrap-2.1.0-py3-none-any.whl
.
File metadata
- Download URL: pmbootstrap-2.1.0-py3-none-any.whl
- Upload date:
- Size: 251.9 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/4.0.2 CPython/3.11.6
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 | c4afd17f73da8ee558c033809bbb6d0c5219c582a17c2859b57938a9090e30e9 |
|
MD5 | 428dfd32b61ce0486aa6d59c9d219d9e |
|
BLAKE2b-256 | e1f838fb31e149a5ab4294e20f295199614054e5c861c9c2317134f6172dc46c |