2017-05-26 20:09:50 +00:00
|
|
|
# pmbootstrap
|
2017-08-16 20:45:31 +00:00
|
|
|
|
2022-10-25 19:58:04 +00:00
|
|
|
Sophisticated chroot/build/flash tool to develop and install
|
|
|
|
[postmarketOS](https://postmarketos.org).
|
2017-05-28 01:01:27 +00:00
|
|
|
|
2022-10-25 20:07:56 +00:00
|
|
|
## Development
|
|
|
|
|
|
|
|
pmbootstrap is being developed on SourceHut
|
|
|
|
([what](https://postmarketos.org/blog/2022/07/25/considering-sourcehut/)):
|
2022-10-25 20:41:23 +00:00
|
|
|
|
2022-10-25 20:07:56 +00:00
|
|
|
https://git.sr.ht/~postmarketos/pmbootstrap
|
|
|
|
|
|
|
|
Send patches via mail or web UI to
|
2022-10-25 22:33:58 +00:00
|
|
|
[pmbootstrap-devel](https://lists.sr.ht/~postmarketos/pmbootstrap-devel)
|
|
|
|
([subscribe](mailto:~postmarketos/pmbootstrap-devel+subscribe@lists.sr.ht)):
|
2022-10-25 20:07:56 +00:00
|
|
|
```
|
|
|
|
~postmarketos/pmbootstrap-devel@lists.sr.ht
|
|
|
|
```
|
|
|
|
|
2022-10-27 20:43:56 +00:00
|
|
|
You can set the default values for sending email in the git checkout
|
|
|
|
```
|
|
|
|
$ git config sendemail.to "~postmarketos/pmbootstrap-devel@lists.sr.ht"
|
|
|
|
$ git config format.subjectPrefix "PATCH pmbootstrap"
|
|
|
|
```
|
|
|
|
|
2022-10-25 20:07:56 +00:00
|
|
|
Run CI scripts locally with:
|
|
|
|
```
|
|
|
|
$ pmbootstrap ci
|
|
|
|
```
|
|
|
|
|
|
|
|
Run a single test file:
|
|
|
|
```
|
|
|
|
$ pytest -vv ./test/test_keys.py
|
|
|
|
```
|
|
|
|
|
2022-10-25 20:48:58 +00:00
|
|
|
## Issues
|
|
|
|
|
|
|
|
Issues are being tracked
|
|
|
|
[here](https://gitlab.com/postmarketOS/pmbootstrap/-/issues).
|
|
|
|
|
2017-05-26 20:09:50 +00:00
|
|
|
## Requirements
|
2018-09-26 05:58:11 +00:00
|
|
|
* Linux distribution on the host system (`x86`, `x86_64`, or `aarch64`)
|
2022-10-25 19:58:04 +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.
|
2018-09-26 05:58:11 +00:00
|
|
|
* [Linux kernel 3.17 or higher](https://postmarketos.org/oldkernel)
|
2023-03-26 16:49:33 +00:00
|
|
|
* Python 3.7+
|
2017-05-27 23:13:29 +00:00
|
|
|
* OpenSSL
|
2019-12-22 11:11:21 +00:00
|
|
|
* git
|
2022-10-31 11:16:14 +00:00
|
|
|
* ps
|
|
|
|
* tar
|
2017-05-26 20:09:50 +00:00
|
|
|
|
2018-03-20 22:00:14 +00:00
|
|
|
## Usage Examples
|
2022-10-25 19:58:04 +00:00
|
|
|
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
|
|
|
```
|
|
|
|
|
2020-02-27 20:42:33 +00:00
|
|
|
Quick health check and config overview:
|
|
|
|
```
|
|
|
|
$ pmbootstrap status
|
|
|
|
```
|
|
|
|
|
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
|
|
|
|
2023-04-30 16:29:26 +00:00
|
|
|
#### 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:
|
|
|
|
```
|
|
|
|
$ 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:
|
|
|
|
```
|
|
|
|
$ pmbootstrap config build_default_device_arch True
|
|
|
|
```
|
|
|
|
|
|
|
|
If your target device is `pine64-pinephone` for example, pmbootstrap will now
|
|
|
|
build this package for `aarch64`:
|
|
|
|
```
|
|
|
|
$ pmbootstrap build hello-world
|
|
|
|
```
|
|
|
|
|
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
|
2022-10-25 19:58:04 +00:00
|
|
|
Analyze Android
|
|
|
|
[`boot.img`](https://wiki.postmarketos.org/wiki/Glossary#boot.img) files (also
|
|
|
|
works with recovery OS images like TWRP):
|
2018-03-20 22:00:14 +00:00
|
|
|
```
|
|
|
|
$ 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
|
|
|
|
```
|
|
|
|
|
2022-10-25 19:58:04 +00:00
|
|
|
Increase the `pkgrel` for each aport where the binary package has outdated
|
|
|
|
dependencies (e.g. after soname bumps):
|
2018-03-20 22:00:14 +00:00
|
|
|
```
|
|
|
|
$ pmbootstrap pkgrel_bump --auto
|
|
|
|
```
|
|
|
|
|
2022-10-25 19:58:04 +00:00
|
|
|
Generate cross-compiler aports based on the latest version from Alpine's
|
|
|
|
aports:
|
2018-03-20 22:00:14 +00:00
|
|
|
```
|
|
|
|
$ 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
|
|
|
|
```
|
|
|
|
|
2020-10-28 17:31:40 +00:00
|
|
|
Parse a single deviceinfo and return it as JSON:
|
|
|
|
```
|
|
|
|
$ pmbootstrap deviceinfo_parse pine64-pinephone
|
|
|
|
```
|
|
|
|
|
2018-03-20 22:00:14 +00:00
|
|
|
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
|
|
|
|
```
|
|
|
|
|
2021-08-09 03:14:39 +00:00
|
|
|
### Use alternative sudo
|
|
|
|
|
|
|
|
pmbootstrap supports `doas` and `sudo`.
|
|
|
|
If multiple sudo implementations are installed, pmbootstrap will use `doas`.
|
2022-10-25 19:58:04 +00:00
|
|
|
You can set the `PMB_SUDO` environmental variable to define the sudo
|
|
|
|
implementation you want to use.
|
2021-08-09 03:14:39 +00:00
|
|
|
|
2022-02-09 16:06:59 +00:00
|
|
|
### Select SSH keys to include and make authorized in new images
|
|
|
|
|
2022-10-25 19:58:04 +00:00
|
|
|
If the config file option `ssh_keys` is set to `True` (it defaults to `False`),
|
|
|
|
then all files matching the glob `~/.ssh/id_*.pub` will be placed in
|
|
|
|
`~/.ssh/authorized_keys` in the user's home directory in newly-built images.
|
2022-02-09 16:06:59 +00:00
|
|
|
|
2022-10-25 19:58:04 +00:00
|
|
|
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.
|
2022-02-09 16:06:59 +00:00
|
|
|
|
|
|
|
For example, a `~/.config/pmbootstrap.cfg` may contain:
|
|
|
|
|
|
|
|
[pmbootstrap]
|
|
|
|
# ...
|
|
|
|
ssh_keys = True
|
|
|
|
ssh_key_glob = ~/.ssh/postmarketos-dev.pub
|
|
|
|
# ...
|
|
|
|
|
2017-08-16 20:45:31 +00:00
|
|
|
## License
|
|
|
|
[GPLv3](LICENSE)
|