2017-05-26 20:09:50 +00:00
# pmbootstrap
2018-06-30 07:00:48 +00:00
[**Introduction** ](https://postmarketos.org/blog/2017/05/26/intro/ ) | [**Security Warning** ](https://ollieparanoid.github.io/post/security-warning/ ) | [**Devices** ](https://wiki.postmarketos.org/wiki/Devices )
2017-08-16 20:45:31 +00:00
2018-03-20 22:00:14 +00:00
Sophisticated chroot/build/flash tool to develop and install [postmarketOS ](https://postmarketos.org ).
2017-05-28 01:01:27 +00:00
2018-09-05 05:57:38 +00:00
Package build scripts live in the [`pmaports` ](https://gitlab.com/postmarketOS/pmaports ) repository now.
2017-05-26 20:09:50 +00:00
## Requirements
2017-08-24 17:33:22 +00:00
* 2 GB of RAM recommended for compiling
2018-09-26 05:58:11 +00:00
* Linux distribution on the host system (`x86`, `x86_64` , or `aarch64` )
2017-10-04 18:17:22 +00:00
* [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.
* Kernels based on the grsec patchset [do **not** work ](https://github.com/postmarketOS/pmbootstrap/issues/107 ) *(Alpine: use linux-vanilla instead of linux-hardened, Arch: linux-hardened [is not based on grsec](https://www.reddit.com/r/archlinux/comments/68b2jn/linuxhardened_in_community_repo_a_grsecurity/))*
2018-09-25 01:33:38 +00:00
* On Alpine Linux only: `apk add coreutils procps`
2018-09-26 05:58:11 +00:00
* [Linux kernel 3.17 or higher ](https://postmarketos.org/oldkernel )
2017-08-16 20:45:31 +00:00
* Python 3.4+
2017-05-27 23:13:29 +00:00
* OpenSSL
2019-12-22 11:11:21 +00:00
* git
2017-05-26 20:09:50 +00:00
2018-03-20 22:00:14 +00:00
## 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` .
2017-05-26 20:09:50 +00:00
2018-08-27 21:35:05 +00:00
### Installing pmbootstrap
< https: / / wiki . postmarketos . org / wiki / Installing_pmbootstrap >
2018-03-20 22:00:14 +00:00
### Basics
Initial setup:
```
$ pmbootstrap init
2017-08-16 20:45:31 +00:00
```
2018-03-20 22:00:14 +00:00
Run this in a second window to see all shell commands that get executed:
```
$ pmbootstrap log
2017-08-16 20:45:31 +00:00
```
2018-03-20 22:00:14 +00:00
### Packages
Build `aports/main/hello-world` :
```
$ pmbootstrap build hello-world
```
2017-05-27 22:57:21 +00:00
2018-03-20 22:00:14 +00:00
Cross-compile to `armhf` :
```
$ pmbootstrap build --arch=armhf hello-world
2017-08-16 20:45:31 +00:00
```
2017-05-26 20:09:50 +00:00
2018-03-20 22:00:14 +00:00
Build with source code from local folder:
```
$ pmbootstrap build linux-postmarketos-mainline --src=~/code/linux
```
2017-05-26 20:09:50 +00:00
2018-03-20 22:00:14 +00:00
Update checksums:
```
$ pmbootstrap checksum hello-world
2017-08-16 20:45:31 +00:00
```
2017-05-26 20:09:50 +00:00
2018-03-20 22:00:14 +00:00
Generate a template for a new package:
```
2018-07-08 23:20:13 +00:00
$ pmbootstrap newapkbuild "https://gitlab.com/postmarketOS/osk-sdl/-/archive/0.52/osk-sdl-0.52.tar.bz2"
2018-03-20 22:00:14 +00:00
```
2017-05-26 20:09:50 +00:00
2018-03-20 22:00:14 +00:00
### Chroots
Enter the `armhf` building chroot:
```
$ pmbootstrap chroot -b armhf
2017-08-16 20:45:31 +00:00
```
2017-05-26 20:09:50 +00:00
2018-03-20 22:00:14 +00:00
Run a command inside a chroot:
```
$ pmbootstrap chroot -- echo test
```
2017-05-26 20:09:50 +00:00
2018-03-20 22:00:14 +00:00
Safely delete all chroots:
```
$ pmbootstrap zap
```
2017-05-26 20:09:50 +00:00
2018-03-20 22:00:14 +00:00
### Device Porting Assistance
Analyze Android [`boot.img` ](https://wiki.postmarketos.org/wiki/Glossary#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:
```
2018-06-09 06:52:24 +00:00
$ pmbootstrap kconfig check
2018-03-20 22:00:14 +00:00
```
Edit a kernel config:
```
2018-06-09 06:52:24 +00:00
$ pmbootstrap kconfig edit --arch=armhf postmarketos-mainline
2018-03-20 22:00:14 +00:00
```
2018-07-15 21:41:31 +00:00
### Root File System
Build the rootfs:
2018-03-20 22:00:14 +00:00
```
$ pmbootstrap install
```
2019-07-01 16:42:58 +00:00
Build the rootfs with full disk encryption:
2018-03-20 22:00:14 +00:00
```
2019-07-01 16:42:58 +00:00
$ pmbootstrap install --fde
```
Update existing installation on SD card:
```
$ pmbootstrap install --sdcard=/dev/mmcblk0 --rsync
2018-03-20 22:00:14 +00:00
```
2019-07-03 21:01:56 +00:00
Run the image in QEMU:
2018-03-20 22:00:14 +00:00
```
$ pmbootstrap qemu --image-size=1G
```
Flash to the device:
```
$ pmbootstrap flasher flash_kernel
2018-03-30 01:11:20 +00:00
$ pmbootstrap flasher flash_rootfs --partition=userdata
2018-03-20 22:00:14 +00:00
```
2018-03-30 01:11:20 +00:00
Export the rootfs, kernel, initramfs, `boot.img` etc.:
2018-03-20 22:00:14 +00:00
```
$ 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
new action: 'pmbootstrap repo_missing'
Add a new action that lists all aports, for which no binary packages
exist. Only list packages that can be built for the relevant arch
(specified with --arch). This works recursively: when a package can be
built for a certain arch, but one of its dependencies
(or their depends) can not be built for that arch, then don't list it.
This action will be used for the new sr.ht based build infrastructure,
to figure out which packages need to be built ahead of time (so we can
trigger each of them as single build job). Determining the order of the
packages to be built is not determined with pmbootstrap, the serverside
code of build.postmarketos.org takes care of that.
For testing purposes, a single package can also be specified and the
action will list if it can be built for that arch with its
dependencies, and what needs to be built exactly.
Add pmb/helpers/package.py to hold functions that work on both pmaports
and (binary package) repos - in contrary to the existing
pmb/helpers/pmaports.py (see previous commit) and pmb/helpers/repo.py,
which only work with one of those.
Refactoring:
* pmb/helpers/pmaports.py: add a get_list() function, which lists all
aports and use it instead of writing the same glob loop over and over
* add pmb.helpers.pmaports.get(), which finds an APKBUILD and parses it
in one step.
* rename pmb.build._package.check_arch to ...check_arch_abort to
distinguish it from the other check_arch function
2018-11-15 07:36:39 +00:00
List pmaports that don't have a binary package:
```
$ pmbootstrap repo_missing --arch=armhf --overview
```
2018-03-20 22:00:14 +00:00
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 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
### Testing
2017-08-16 20:45:31 +00:00
Install `pytest` (via your package manager or pip) and run it inside the pmbootstrap folder.
2017-05-26 20:09:50 +00:00
2017-08-16 20:45:31 +00:00
## License
[GPLv3 ](LICENSE )