User:knuxfanwin8/Draft:pmbootstrap
🚧 | This page is a work-in-progress. Some information contained within may be inaccurate or incomplete.
In particular: This is a layout for a potential pmbootstrap page rewrite. It's completely empty as of now, but will eventually be filled with more useful information. |
pmbootstrap is postmarketOS's dedicated build tool. This page contains a brief explanation of how it works, as well as some tips and tricks for using it.
How it works
pmbootstrap uses chroots, small self-contained installations of postmarketOS (technically Alpine Linux), to manage all build dependencies. This way, the user doesn't have to set up any build dependencies manually, outside of pmbootstrap.
pmbootstrap manages building packages, including cross-compilation, as well as postmarketOS image generation and a few other development tools.
Installing pmbootstrap
Installing from a distribution package
Some distributions package pmbootstrap. If your distribution is among them, and the version isn't too outdated, you can usually get the pmbootstrap
package from your preferred package manager.
An overview of pmbootstrap versions in various package repositories can be found on Repology.
Installing from git
If your distribution doesn't offer a pmbootstrap package, or if it's outdated, or if you just want the latest development version of pmbootstrap, you can also get it directly from its repository.
$ git clone --depth=1 https://gitlab.com/postmarketOS/pmbootstrap.git
$ mkdir -p ~/.local/bin
$ ln -s "$PWD/pmbootstrap/pmbootstrap.py" ~/.local/bin/pmbootstrap
$ pmbootstrap --version
2.1.0
If this returns something like pmbootstrap: command not found
instead of a version number, you may need to add ~/.local/bin
to your PATH
variable. This can be done by adding the following to your ~/.profile
(zsh: ~/.zprofile
) (you can also source ~/.profile
to apply your changes immediately):
PATH="$HOME/.local/bin:$PATH"
Then open a new terminal and try again.
First steps
The first step to working with pmbootstrap is initializing it. You can do this by running:
$ pmbootstrap init
This will display a few prompts that will allow you to select the work path, the device you're developing for and some installation-related settings.
TODO: pmbootstrap init and related options.
Work directory
TODO: talk about work dir layout and what to watch out for
Viewing the log
TODO: explain pmbootstrap log, log file location, what to post when troubleshooting, etc.
Checking the status and updating pmaports
TODO: explain pmbootstrap status and pmbootstrap pull
Installing postmarketOS with pmbootstrap
One of pmbootstrap's main features is the ability to build and flash a postmarketOS image. This section describes some of the useful commands; for a proper guide, see Installation/Using pmbootstrap.
Flashing postmarketOS
TODO
Exporting images
TODO: explain pmbootstrap export and flashing custom images, pmbootstrap initfs extract
Device porting assistance
TODO: brief mention of the tools, redirect to porting guide
Building packages
TODO: explain pmbootstrap checksum, pmbootstrap build; talk about apkbuild format and link apkbuild reference; pmbootstrap build --src
Creating a new package
TODO: explain pmbootstrap newapkbuild
Forking a package from Alpine
TODO: explain pmbootstrap aportgen
Sideloading built packages
TODO: explain pmbootstrap sideload
Chroot management
TODO: explain pmbootstrap chroot and what each chroot does/is used for; also pmbootstrap shutdown
Entering the chroot
TODO: pmbootstrap chroot intro
Zapping the chroot
TODO: pmbootstrap zap brief intro
Cleaning up
TODO: explain the different prompts and flags for pmbootstrap zap and what they're useful for
Advanced tools
These are mostly useful to postmarketOS maintainers.
Repository maintenance
TODO: pmbootstrap#Repository maintenance
Running CI scripts locally
TODO: pmbootstrap#Running CI scripts locally
Troubleshooting
TODO: call back to pmbootstrap log, help channels, bug reporting, etc.