# pmbootstrap Sophisticated chroot/build/flash tool to develop and install [postmarketOS](https://postmarketos.org). ## Development Find the location of the upstream repository for pmbootstrap on the [postmarketOS homepage](https://postmarketos.org/source-code/). Run CI scripts locally with: ```sh pmbootstrap ci ``` Run a single test file: ```sh pytest -vv ./test/test_keys.py ``` ## Issues [Issues are being tracked in the GitLab issue tracker](https://gitlab.postmarketos.org/postmarketOS/pmbootstrap/-/issues). ## Requirements * Linux distribution on the host system (`x86`, `x86_64`, `aarch64` or `armv7`) * [Windows subsystem for Linux (WSL)](https://en.wikipedia.org/wiki/Windows_Subsystem_for_Linux) does **not** work! Please use [VirtualBox](https://www.virtualbox.org/) instead. * [Linux kernel 3.17 or higher](https://postmarketos.org/oldkernel) * Note: kernel versions between 5.8.8 and 6.0 might [have issues with parted](https://gitlab.postmarketos.org/postmarketOS/pmbootstrap/-/issues/2309). * Python 3.10+ * For python3 < 3.11: tomli * OpenSSL * git * kpartx (from multipath-tools) * losetup (with --json support, e.g. util-linux version) * ps * tar ## Relation to pmaports For pmbootstrap to be useful, it needs to maintain a local copy of the [pmaports](https://gitlab.postmarketos.org/postmarketOS/pmaports) repository where postmarketOS-specific packages are maintained. This is set up automatically, but the local copy of pmaports does not automatically get updated. To update it, you can run `$ pmbootstrap pull`. The latest pmbootstrap version works with currently [active postmarketOS releases](https://wiki.postmarketos.org/wiki/Releases). Attempting to use pmboostrap with old postmarketOS versions (old pmaports branches) may result in failures and is not supported. See `pmbootstrap_min_version` in [pmaports.cfg](https://wiki.postmarketos.org/wiki/Pmaports.cfg_reference) for the oldest supported pmbootstrap version for a given pmaports revision. The upper bound is not documented. ## Usage Examples Please refer to the [postmarketOS wiki](https://wiki.postmarketos.org) for in-depth coverage of topics such as [porting to a new device](https://wiki.postmarketos.org/wiki/Porting_to_a_new_device) or [installation](https://wiki.postmarketos.org/wiki/Installation_guide). 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 ### Basics Initial setup: ```sh pmbootstrap init ``` Run this in a second window to see all shell commands that get executed: ```sh pmbootstrap log ``` Quick health check and config overview: ```sh pmbootstrap status ``` ### Packages Build `aports/main/hello-world`: ```sh pmbootstrap build hello-world ``` Cross-compile to `armhf`: ```sh pmbootstrap build --arch=armhf hello-world ``` Build with source code from local folder: ```sh pmbootstrap build linux-postmarketos-mainline --src=~/code/linux ``` Update checksums: ```sh pmbootstrap checksum hello-world ``` Generate a template for a new package: ```sh pmbootstrap newapkbuild "https://gitlab.postmarketos.org/postmarketOS/tinydm/-/archive/1.2.0/tinydm-1.2.0.tar.gz" ``` #### 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: ```sh 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: ```sh pmbootstrap config build_default_device_arch True ``` If your target device is `pine64-pinephone` for example, pmbootstrap will now build this package for `aarch64`: ```sh pmbootstrap build hello-world ``` ### Chroots Enter the `armhf` building chroot: ```sh pmbootstrap chroot -b armhf ``` Run a command inside a chroot: ```sh pmbootstrap chroot -- echo test ``` Safely delete all chroots: ```sh pmbootstrap zap ``` ### Device Porting Assistance Analyze Android [`boot.img`](https://wiki.postmarketos.org/wiki/Glossary#boot.img) files (also works with recovery OS images like TWRP): ```sh pmbootstrap bootimg_analyze ~/Downloads/twrp-3.2.1-0-fp2.img ``` Check kernel configs: ```sh pmbootstrap kconfig check ``` Edit a kernel config: ```sh pmbootstrap kconfig edit --arch=armhf postmarketos-mainline ``` ### Root File System Build the rootfs: ```sh pmbootstrap install ``` Build the rootfs with full disk encryption: ```sh pmbootstrap install --fde ``` Update existing installation on SD card: ```sh pmbootstrap install --disk=/dev/mmcblk0 --rsync ``` Run the image in QEMU: ```sh pmbootstrap qemu --image-size=1G ``` Flash to the device: ```sh pmbootstrap flasher flash_kernel pmbootstrap flasher flash_rootfs --partition=userdata ``` Export the rootfs, kernel, initramfs, `boot.img` etc.: ```sh pmbootstrap export ``` Extract the initramfs ```sh pmbootstrap initfs extract ``` Build and flash Android recovery zip: ```sh pmbootstrap install --android-recovery-zip pmbootstrap flasher --method=adb sideload ``` ### Repository Maintenance List pmaports that don't have a binary package: ```sh pmbootstrap repo_missing --arch=armhf --overview ``` Increase the `pkgrel` for each aport where the binary package has outdated dependencies (e.g. after soname bumps): ```sh pmbootstrap pkgrel_bump --auto ``` Generate cross-compiler aports based on the latest version from Alpine's aports: ```sh pmbootstrap aportgen gcc-armhf ``` Manually rebuild package index: ```sh pmbootstrap index ``` Delete local binary packages without existing aport of same version: ```sh pmbootstrap zap -m ``` ### Debugging Use `-v` on any action to get verbose logging: ```sh pmbootstrap -v build hello-world ``` Parse a single APKBUILD and return it as JSON: ```sh pmbootstrap apkbuild_parse hello-world ``` Parse a package from an APKINDEX and return it as JSON: ```sh pmbootstrap apkindex_parse $WORK/cache_apk_x86_64/APKINDEX.8b865e19.tar.gz hello-world ``` `ccache` statistics: ```sh pmbootstrap stats --arch=armhf ``` ### Use alternative sudo See `PMB_SUDO` in `docs/environment_variables.md`. ### 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/*.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_v3.cfg` may contain: ```ini [pmbootstrap] # ... ssh_keys = True ssh_key_glob = ~/.ssh/postmarketos-dev.pub # ... ``` ## License [GPLv3](LICENSE)