8ace36113c
The provider selection for "pmbootstrap init" added in this commit is a flexible way to offer UI/device-specific configuration options in "pmbootstrap init", without hardcoding them in pmbootstrap. Instead, the options are defined entirely in pmaports using APK's virtual package provider mechanism. The code in pmbootstrap searches for available providers and displays them together with their pkgdesc. There are many possible use cases for this but I have tested two so far: 1. Selecting root provider (sudo vs doas). This can be defined entirely in postmarketos-base, without having to handle this specifically in pmbootstrap. $ pmbootstrap init [...] Available providers for postmarketos-root (2): * sudo: Use sudo to run root commands (**default**) * doas: Use doas (minimal replacement for sudo) to run root commands (Note: Does not support all functionality of sudo) Provider [default]: doas 2. Device-specific options. My main motivation for working on this feature is a new configuration option for the MSM8916-based devices. It allows more control about which firmware to enable: $ pmbootstrap init [...] Available providers for soc-qcom-msm8916-rproc (3): * all: Enable all remote processors (audio goes through modem) (default) * no-modem: Disable only modem (audio bypasses modem, ~80 MiB more RAM) * none: Disable all remote processors (no WiFi/BT/modem, ~90 MiB more RAM) Provider [default]: no-modem The configuration prompts show up dynamically by defining _pmb_select="<virtual packages>" in postmarketos-base, a UI PKGBUILD or the device APKBUILD. Selecting "default" (just pressing enter) means that no provider is selected. This allows APK to choose it automatically based on the "provider_priority". It also provides compatibility with existing installation; APK will just choose the default provider when upgrading. The selection can still be changed after installation by installing another provider using "apk". Note that at the end this is just a more convenient interface for the already existing "extra packages" prompt. When using pmbootstrap in automated scripts the providers (e.g. "postmarketos-root-doas") can be simply selected through the existing "extra_packages" option. |
||
---|---|---|
.ci | ||
helpers | ||
pmb | ||
test | ||
.gitignore | ||
.gitlab-ci.yml | ||
CONTRIBUTING.md | ||
LICENSE | ||
MANIFEST.in | ||
README.md | ||
pmbootstrap.py | ||
setup.cfg | ||
setup.py |
README.md
pmbootstrap
Introduction | Security Warning | Devices
Sophisticated chroot/build/flash tool to develop and install postmarketOS.
Package build scripts live in the pmaports
repository now.
Requirements
- 2 GB of RAM recommended for compiling
- Linux distribution on the host system (
x86
,x86_64
, oraarch64
)- Windows subsystem for Linux (WSL) does not work! Please use VirtualBox instead.
- Kernels based on the grsec patchset do not work
- Linux kernel 3.17 or higher
- Python 3.6+
- OpenSSL
- git
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"
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 --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
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
distccd
log:
$ pmbootstrap log_distccd
Development
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/static_code_analysis.sh
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/pytest.sh
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/test_keys.py