Install osk-sdl in the installer OS's boot partition for now. I forgot about a code path earlier, which could render an encrypted target OS without osk-sdl in the initramfs (and being unable to boot). The target OS gets embeded in the installer OS as image file. This can happen in two formats: a) a full image with partition header and the boot and root partition This is what bpo is doing when building the official, pre-built images, as this method allows having the exact same image available separately without the installer. Basically: pmbootstrap install \ --ondev \ --no-rootfs \ --cp path/to/rootfs:/var/lib/rootfs.img b) an image with just the root partition, no partition header and no boot partition. This is what you get when running regular "pmbootstrap install --ondev". It's slightly smaller, as there is no duplicate boot partition. If b) was done, the installer will copy the contents of the installer's boot partition to the target OS. And that means: if osk-sdl is missing from the installer's boot partition (the initramfs generated there), it will also be missing in the boot partition of the target OS! I think we should get rid of the b) code path to avoid confusion in the future/make maintenance. But until that is done, always install osk-sdl into the installer OS. |
||
---|---|---|
.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