# pmbootstrap
Sophisticated chroot/build/flash tool to develop and install
[postmarketOS](https://postmarketos.org).
## Development
pmbootstrap is being developed on SourceHut
([what](https://postmarketos.org/blog/2022/07/25/considering-sourcehut/)):
https://git.sr.ht/~postmarketos/pmbootstrap
Send patches via mail or web UI to
[pmbootstrap-devel](https://lists.sr.ht/~postmarketos/pmbootstrap-devel)
([subscribe](mailto:~postmarketos/pmbootstrap-devel+subscribe@lists.sr.ht)):
```
~postmarketos/pmbootstrap-devel@lists.sr.ht
```
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"
```
Run CI scripts locally with:
```
$ pmbootstrap ci
```
Run a single test file:
```
$ pytest -vv ./test/test_keys.py
```
## Issues
Issues are being tracked
[here](https://gitlab.com/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)
* Python 3.7+
* OpenSSL
* git
* ps
* tar
## 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
<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"
```
#### 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
```
### 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`](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:
```
$ 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 --disk=/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 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
```
### Use alternative sudo
pmbootstrap supports `doas` and `sudo`.
If multiple sudo implementations are installed, pmbootstrap will use `doas`.
You can set the `PMB_SUDO` environmental variable to define the sudo
implementation you want to use.
### 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/id_*.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.cfg` may contain:
[pmbootstrap]
# ...
ssh_keys = True
ssh_key_glob = ~/.ssh/postmarketos-dev.pub
# ...
## License
[GPLv3](LICENSE)
Raw data
{
"_id": null,
"home_page": "https://www.postmarketos.org",
"name": "pmbootstrap",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "",
"keywords": "postmarketos pmbootstrap",
"author": "postmarketOS Developers",
"author_email": "info@postmarketos.org",
"download_url": "https://files.pythonhosted.org/packages/fe/03/3a2dbcdc5dc080e5221e6a3977331e456820e85e5680c754e38d6f4a8bce/pmbootstrap-2.1.0.tar.gz",
"platform": null,
"description": "# pmbootstrap\n\nSophisticated chroot/build/flash tool to develop and install\n[postmarketOS](https://postmarketos.org).\n\n## Development\n\npmbootstrap is being developed on SourceHut\n([what](https://postmarketos.org/blog/2022/07/25/considering-sourcehut/)):\n\nhttps://git.sr.ht/~postmarketos/pmbootstrap\n\nSend patches via mail or web UI to\n[pmbootstrap-devel](https://lists.sr.ht/~postmarketos/pmbootstrap-devel)\n([subscribe](mailto:~postmarketos/pmbootstrap-devel+subscribe@lists.sr.ht)):\n```\n~postmarketos/pmbootstrap-devel@lists.sr.ht\n```\n\nYou can set the default values for sending email in the git checkout\n```\n$ git config sendemail.to \"~postmarketos/pmbootstrap-devel@lists.sr.ht\"\n$ git config format.subjectPrefix \"PATCH pmbootstrap\"\n```\n\nRun CI scripts locally with:\n```\n$ pmbootstrap ci\n```\n\nRun a single test file:\n```\n$ pytest -vv ./test/test_keys.py\n```\n\n## Issues\n\nIssues are being tracked\n[here](https://gitlab.com/postmarketOS/pmbootstrap/-/issues).\n\n## Requirements\n* Linux distribution on the host system (`x86`, `x86_64`, `aarch64` or `armv7`)\n * [Windows subsystem for Linux (WSL)](https://en.wikipedia.org/wiki/Windows_Subsystem_for_Linux)\n does **not** work! Please use [VirtualBox](https://www.virtualbox.org/) instead.\n * [Linux kernel 3.17 or higher](https://postmarketos.org/oldkernel)\n* Python 3.7+\n* OpenSSL\n* git\n* ps\n* tar\n\n## Usage Examples\nPlease refer to the [postmarketOS wiki](https://wiki.postmarketos.org) for\nin-depth coverage of topics such as\n[porting to a new device](https://wiki.postmarketos.org/wiki/Porting_to_a_new_device)\nor [installation](https://wiki.postmarketos.org/wiki/Installation_guide). The\nhelp output (`pmbootstrap -h`) has detailed usage instructions for every\ncommand. Read on for some generic examples of what can be done with\n`pmbootstrap`.\n\n### Installing pmbootstrap\n<https://wiki.postmarketos.org/wiki/Installing_pmbootstrap>\n\n### Basics\nInitial setup:\n```\n$ pmbootstrap init\n```\n\nRun this in a second window to see all shell commands that get executed:\n```\n$ pmbootstrap log\n```\n\nQuick health check and config overview:\n```\n$ pmbootstrap status\n```\n\n### Packages\nBuild `aports/main/hello-world`:\n```\n$ pmbootstrap build hello-world\n```\n\nCross-compile to `armhf`:\n```\n$ pmbootstrap build --arch=armhf hello-world\n```\n\nBuild with source code from local folder:\n```\n$ pmbootstrap build linux-postmarketos-mainline --src=~/code/linux\n```\n\nUpdate checksums:\n```\n$ pmbootstrap checksum hello-world\n```\n\nGenerate a template for a new package:\n```\n$ pmbootstrap newapkbuild \"https://gitlab.com/postmarketOS/osk-sdl/-/archive/0.52/osk-sdl-0.52.tar.bz2\"\n```\n\n#### Default architecture\n\nPackages will be compiled for the architecture of the device running\npmbootstrap by default. For example, if your `x86_64` PC runs pmbootstrap, it\nwould build a package for `x86_64` with this command:\n```\n$ pmbootstrap build hello-world\n```\n\nIf you would rather build for the target device selected in `pmbootstrap init`\nby default, then use the `build_default_device_arch` option:\n```\n$ pmbootstrap config build_default_device_arch True\n```\n\nIf your target device is `pine64-pinephone` for example, pmbootstrap will now\nbuild this package for `aarch64`:\n```\n$ pmbootstrap build hello-world\n```\n\n### Chroots\nEnter the `armhf` building chroot:\n```\n$ pmbootstrap chroot -b armhf\n```\n\nRun a command inside a chroot:\n```\n$ pmbootstrap chroot -- echo test\n```\n\nSafely delete all chroots:\n```\n$ pmbootstrap zap\n```\n\n### Device Porting Assistance\nAnalyze Android\n[`boot.img`](https://wiki.postmarketos.org/wiki/Glossary#boot.img) files (also\nworks with recovery OS images like TWRP):\n```\n$ pmbootstrap bootimg_analyze ~/Downloads/twrp-3.2.1-0-fp2.img\n```\n\nCheck kernel configs:\n```\n$ pmbootstrap kconfig check\n```\n\nEdit a kernel config:\n```\n$ pmbootstrap kconfig edit --arch=armhf postmarketos-mainline\n```\n\n### Root File System\nBuild the rootfs:\n```\n$ pmbootstrap install\n```\n\nBuild the rootfs with full disk encryption:\n```\n$ pmbootstrap install --fde\n```\n\nUpdate existing installation on SD card:\n```\n$ pmbootstrap install --disk=/dev/mmcblk0 --rsync\n```\n\nRun the image in QEMU:\n```\n$ pmbootstrap qemu --image-size=1G\n```\n\nFlash to the device:\n```\n$ pmbootstrap flasher flash_kernel\n$ pmbootstrap flasher flash_rootfs --partition=userdata\n```\n\nExport the rootfs, kernel, initramfs, `boot.img` etc.:\n```\n$ pmbootstrap export\n```\n\nExtract the initramfs\n```\n$ pmbootstrap initfs extract\n```\n\nBuild and flash Android recovery zip:\n```\n$ pmbootstrap install --android-recovery-zip\n$ pmbootstrap flasher --method=adb sideload\n```\n\n### Repository Maintenance\nList pmaports that don't have a binary package:\n```\n$ pmbootstrap repo_missing --arch=armhf --overview\n```\n\nIncrease the `pkgrel` for each aport where the binary package has outdated\ndependencies (e.g. after soname bumps):\n```\n$ pmbootstrap pkgrel_bump --auto\n```\n\nGenerate cross-compiler aports based on the latest version from Alpine's\naports:\n```\n$ pmbootstrap aportgen gcc-armhf\n```\n\nManually rebuild package index:\n```\n$ pmbootstrap index\n```\n\nDelete local binary packages without existing aport of same version:\n```\n$ pmbootstrap zap -m\n```\n\n### Debugging\nUse `-v` on any action to get verbose logging:\n```\n$ pmbootstrap -v build hello-world\n```\n\nParse a single deviceinfo and return it as JSON:\n```\n$ pmbootstrap deviceinfo_parse pine64-pinephone\n```\n\nParse a single APKBUILD and return it as JSON:\n```\n$ pmbootstrap apkbuild_parse hello-world\n```\n\nParse a package from an APKINDEX and return it as JSON:\n```\n$ pmbootstrap apkindex_parse $WORK/cache_apk_x86_64/APKINDEX.8b865e19.tar.gz hello-world\n```\n\n`ccache` statistics:\n```\n$ pmbootstrap stats --arch=armhf\n```\n\n### Use alternative sudo\n\npmbootstrap supports `doas` and `sudo`.\nIf multiple sudo implementations are installed, pmbootstrap will use `doas`.\nYou can set the `PMB_SUDO` environmental variable to define the sudo\nimplementation you want to use.\n\n### Select SSH keys to include and make authorized in new images\n\nIf the config file option `ssh_keys` is set to `True` (it defaults to `False`),\nthen all files matching the glob `~/.ssh/id_*.pub` will be placed in\n`~/.ssh/authorized_keys` in the user's home directory in newly-built images.\n\nSometimes, for example if you have a large number of SSH keys, you may wish to\nselect a different set of public keys to include in an image. To do this, set\nthe `ssh_key_glob` configuration parameter in the pmbootstrap config file to a\nstring containing a glob that is to match the file or files you wish to\ninclude.\n\nFor example, a `~/.config/pmbootstrap.cfg` may contain:\n\n [pmbootstrap]\n # ...\n ssh_keys = True\n ssh_key_glob = ~/.ssh/postmarketos-dev.pub\n # ...\n\n## License\n[GPLv3](LICENSE)\n",
"bugtrack_url": null,
"license": "GPLv3",
"summary": "A sophisticated chroot / build / flash tool to develop and install postmarketOS",
"version": "2.1.0",
"project_urls": {
"Homepage": "https://www.postmarketos.org"
},
"split_keywords": [
"postmarketos",
"pmbootstrap"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "e1f838fb31e149a5ab4294e20f295199614054e5c861c9c2317134f6172dc46c",
"md5": "428dfd32b61ce0486aa6d59c9d219d9e",
"sha256": "c4afd17f73da8ee558c033809bbb6d0c5219c582a17c2859b57938a9090e30e9"
},
"downloads": -1,
"filename": "pmbootstrap-2.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "428dfd32b61ce0486aa6d59c9d219d9e",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 251862,
"upload_time": "2023-12-03T19:32:38",
"upload_time_iso_8601": "2023-12-03T19:32:38.715896Z",
"url": "https://files.pythonhosted.org/packages/e1/f8/38fb31e149a5ab4294e20f295199614054e5c861c9c2317134f6172dc46c/pmbootstrap-2.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "fe033a2dbcdc5dc080e5221e6a3977331e456820e85e5680c754e38d6f4a8bce",
"md5": "72352714cb4f72d3cd7adf58325ac235",
"sha256": "6ee09f42c8b5d0b7b30f361ea6502b985452737bdb8ed97e16e4e6fd5512daeb"
},
"downloads": -1,
"filename": "pmbootstrap-2.1.0.tar.gz",
"has_sig": false,
"md5_digest": "72352714cb4f72d3cd7adf58325ac235",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 236702,
"upload_time": "2023-12-03T19:32:42",
"upload_time_iso_8601": "2023-12-03T19:32:42.668263Z",
"url": "https://files.pythonhosted.org/packages/fe/03/3a2dbcdc5dc080e5221e6a3977331e456820e85e5680c754e38d6f4a8bce/pmbootstrap-2.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-12-03 19:32:42",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "pmbootstrap"
}
JSON