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
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-02-22 21:50:39 +00:00
* Linux distribution (`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/))*
2017-12-27 19:05:59 +00:00
* On Alpine Linux only: `apk add coreutils`
2017-08-16 20:45:31 +00:00
* Python 3.4+
2017-05-27 23:13:29 +00:00
* OpenSSL
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-03-20 22:00:14 +00:00
### Basics
Initial setup:
```
2018-07-08 23:20:13 +00:00
$ git clone https://gitlab.com/postmarketOS/pmbootstrap.git
2017-08-16 20:45:31 +00:00
$ cd pmbootstrap
2018-03-20 22:00:14 +00:00
$ alias pmbootstrap=$PWD/pmbootstrap.py
$ pmbootstrap init
2017-08-16 20:45:31 +00:00
```
2018-03-20 22:00:14 +00:00
To make the `pmbootstrap` alias persistent, [see the wiki ](https://wiki.postmarketos.org/wiki/Porting_to_a_new_device#Shortcut ).
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
```
Update existing installation on SD card (full disk encryption disabled):
```
$ pmbootstrap install --sdcard=/dev/mmcblk0 --no-fde --rsync
```
Run the image in Qemu:
```
$ 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
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 )