User:knuxfanwin8/Draft:pmbootstrap

From postmarketOS


🚧 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

Not to be confused with mrtest.

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.